iCode-TUI 0.29.1__py3-none-any.whl

chrys/service/mcp/result_limits.py

@@ -0,0 +1,168 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Presentation bounds for results produced by remote MCP tools."""
+
+from __future__ import annotations
+
+from copy import copy
+from pathlib import Path
+from typing import Any
+
+from chrys.foundation.text.tool_output import truncate_content_texts, truncate_output
+from chrys.kernel import Content
+from chrys.service.tools.spill import discard_spill, run_spill_finalizer, try_spill_text
+
+DEFAULT_MCP_TOOL_RESULT_MAX_TOKENS = 8000
+MCP_BINARY_MAX_BYTES = 3 * 1024 * 1024
+MCP_RESULT_MAX_TOTAL_BINARY_BYTES = 10 * 1024 * 1024
+MCP_ERROR_TEXT_MAX_TOKENS = 2000
+
+_MCP_PROMPT_TOOL_KEY = "_chrys_mcp_prompt_tool"
+
+
+def resolve_mcp_result_cap(value: int | None) -> int | None:
+    """Resolve an MCP profile cap; ``None`` means default and zero disables."""
+    return DEFAULT_MCP_TOOL_RESULT_MAX_TOKENS if value is None else (None if value == 0 else value)
+
+
+async def truncate_mcp_result(result: Any, budget: int, spill_dir: Path | None) -> Any:
+    """Copy and bound the text-bearing MCP result shapes used by Chrys."""
+    if isinstance(result, str):
+        plain = truncate_output(result, budget)
+        if plain == result:
+            return result
+        return await run_spill_finalizer(_truncate_mcp_string_result, result, budget, spill_dir, plain)
+
+    if not isinstance(result, list):
+        return result
+    text_items = [
+        item for item in result if isinstance(item, Content) and item.type == "text" and item.text is not None
+    ]
+    texts = [item.text for item in text_items]
+    if not texts:
+        return result
+    if truncate_content_texts(texts, budget) is None:
+        return result
+
+    return await run_spill_finalizer(_truncate_mcp_list_result, result, texts, budget, spill_dir)
+
+
+def _truncate_mcp_string_result(result: str, budget: int, spill_dir: Path | None, plain: str) -> str:
+    info = try_spill_text(spill_dir, "mcp", result, budget)
+    bounded = truncate_output(result, budget, truncation_suffix=info.notice if info else "")
+    if info is not None and info.notice not in bounded:
+        discard_spill(info)
+        return plain
+    return bounded
+
+
+def _truncate_mcp_list_result(
+    result: list[Any],
+    texts: list[str],
+    budget: int,
+    spill_dir: Path | None,
+) -> list[Any]:
+
+    worst_dropped_count = max(0, len(texts) - 1)
+    reserved_footer = f"[{worst_dropped_count} further text items omitted.]" if worst_dropped_count else ""
+    joined_texts = "\n\n".join(texts)
+    info = try_spill_text(spill_dir, "mcp", joined_texts, budget, reserved_footer)
+    bounded = truncate_content_texts(texts, budget, truncation_suffix=info.notice if info else "")
+    if bounded is None:
+        raise RuntimeError("MCP text truncation did not return bounded content.")
+    if info is not None and info.notice not in "\n".join(value for value in bounded if value is not None):
+        discard_spill(info)
+        bounded = truncate_content_texts(texts, budget)
+        if bounded is None:
+            raise RuntimeError("MCP text truncation did not return bounded content.")
+
+    output: list[Content] = []
+    text_index = 0
+    for item in result:
+        if isinstance(item, Content) and item.type == "text" and item.text is not None:
+            replacement = bounded[text_index]
+            text_index += 1
+            if replacement is None:
+                continue
+            if replacement == item.text:
+                output.append(item)
+            else:
+                item_copy = copy(item)
+                item_copy.text = replacement
+                output.append(item_copy)
+        else:
+            output.append(item)
+    return output
+
+
+def truncate_mcp_error(text: str) -> str:
+    """Bound server-controlled error text while favoring its leading cause."""
+    return truncate_output(text, MCP_ERROR_TEXT_MAX_TOKENS, head_ratio=2 / 3)
+
+
+def _base64_payload(data: str) -> str:
+    return data.split(",", 1)[1] if data.startswith("data:") and "," in data else data
+
+
+def _estimated_decoded_size(data: str) -> int:
+    return len(_base64_payload(data)) * 3 // 4
+
+
+def _binary_item_info(item: Any) -> tuple[str, int] | None:
+    from mcp import types
+
+    if isinstance(item, types.ImageContent):
+        return "image", _estimated_decoded_size(item.data)
+    if isinstance(item, types.AudioContent):
+        return "audio", _estimated_decoded_size(item.data)
+    if isinstance(item, types.EmbeddedResource) and isinstance(item.resource, types.BlobResourceContents):
+        return "blob", _estimated_decoded_size(item.resource.blob)
+    return None
+
+
+def sanitize_mcp_result_binary(result: Any) -> Any:
+    """Copy an SDK CallToolResult and replace binary payloads before decode."""
+    from mcp import types
+
+    content = list(result.content)
+    sanitized: list[Any] = []
+    cumulative = 0
+    index = 0
+    while index < len(content):
+        item = content[index]
+        info = _binary_item_info(item)
+        if info is None:
+            sanitized.append(item)
+            index += 1
+            continue
+
+        kind, size = info
+        if size > MCP_BINARY_MAX_BYTES:
+            sanitized.append(
+                types.TextContent(
+                    type="text",
+                    text=f"[{kind} omitted: ~{size} exceeds {MCP_BINARY_MAX_BYTES} limit]",
+                )
+            )
+            index += 1
+            continue
+
+        if cumulative + size > MCP_RESULT_MAX_TOTAL_BINARY_BYTES:
+            dropped = sum(1 for remaining in content[index:] if _binary_item_info(remaining) is not None)
+            sanitized.append(
+                types.TextContent(
+                    type="text",
+                    text=(
+                        f"[{dropped} binary items omitted: result exceeds "
+                        f"{MCP_RESULT_MAX_TOTAL_BINARY_BYTES} byte limit]"
+                    ),
+                )
+            )
+            sanitized.extend(remaining for remaining in content[index:] if _binary_item_info(remaining) is None)
+            break
+
+        cumulative += size
+        sanitized.append(item)
+        index += 1
+
+    return result.model_copy(update={"content": sanitized})

chrys/service/mcp/thinking_warning.py

@@ -0,0 +1,95 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""The warning that on-demand MCP tool loading can unbind an agent's preserved thinking.
+
+A server with ``use_progressive_disclosure`` changes the request's tool set
+whenever the model loads or unloads one of its tools, and a new run starts
+again from the initial set. Claude Opus 5.5, Fable 5.1 and Sonnet 5.5 bind
+their replayed thinking to the request prefix, tools included, so after such a
+change the service may refuse a request replaying that thinking, unless the
+request lets it drop the mismatched thinking (``drop_block``). Each agent
+build logs at most one warning for that case, naming the agent, its model
+profile and every such server.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Collection, Mapping
+
+    from chrys.service.profiles.agents.schema import AgentProfile
+    from chrys.service.profiles.models.schema import ModelProfile
+
+logger = logging.getLogger(__name__)
+
+
+def tool_loading_thinking_warning(
+    agent: AgentProfile,
+    model: ModelProfile,
+    chat_options: Mapping[str, Any] | None,
+    connected: Collection[str],
+) -> str | None:
+    """The warning for *agent* running *model* with *chat_options*, or None when there is none.
+
+    *connected* names the agent's MCP servers that connected. The warning
+    applies to an Anthropic profile whose final model binds its thinking, with
+    at least one enabled, connected server loading tools on demand, unless the
+    request turns thinking off or sends ``drop_block``. It names the agent and
+    the model profile, which holds the settings it suggests.
+    """
+    if model.provider != "anthropic":
+        return None
+    names = [
+        config.name
+        for config in agent.tools.mcp
+        if config.enabled and config.use_progressive_disclosure and config.name in connected
+    ]
+    if not names:
+        return None
+
+    # Imported only once an Anthropic profile qualifies: the package loads the Anthropic SDK.
+    from chrys.service.llm.anthropic_messages.thinking_binding import resolve_thinking_binding
+    from chrys.service.llm.clients import effective_model_base_url
+
+    options = chat_options or {}
+    request = dict(options)
+    if not request.get("model"):
+        request["model"] = model.model_id
+    policy = resolve_thinking_binding(request, options, base_url=effective_model_base_url(model))
+    if not policy.binding_model or policy.thinking_type == "disabled":
+        return None
+    if policy.mismatch_behavior_sent and policy.mismatch_behavior == "drop_block":
+        return None
+
+    servers_text = ", ".join(repr(name) for name in names)
+    lead = (
+        f"Agent {agent.name!r} on model profile {model.name!r}: MCP server(s) {servers_text} load tools on demand "
+        "(use_progressive_disclosure). Loading or unloading a tool changes the tool set the model binds its "
+        "earlier thinking to"
+    )
+    if policy.mismatch_behavior == "error":
+        return f"{lead}, so the service can refuse a later request (the prefix mismatch behavior is error)."
+    remedy = (
+        'Writing the block_binding in the thinking as {"prefix_mismatch_behavior": "drop_block"}'
+        if policy.block_binding_written
+        else "Setting thinking_block_binding: drop_block with enabled or adaptive thinking"
+    )
+    return (
+        f"{lead}, so the service can refuse a later request; it is then resent once without the earlier "
+        f"thinking, which the model no longer sees. {remedy} lets the service drop the thinking that no longer "
+        "matches instead."
+    )
+
+
+def warn_if_tool_loading_unbinds_thinking(
+    agent: AgentProfile,
+    model: ModelProfile,
+    chat_options: Mapping[str, Any] | None,
+    connected: Collection[str],
+) -> None:
+    """Log :func:`tool_loading_thinking_warning`'s warning, if there is one."""
+    if (message := tool_loading_thinking_warning(agent, model, chat_options, connected)) is not None:
+        logger.warning("%s", message)

chrys/service/mcp/validation.py

@@ -0,0 +1,74 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Validation helpers for MCP configuration."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Collection
+
+MAX_MCP_EXPOSED_TOOL_NAME_LENGTH = 64
+MCP_PROGRESSIVE_CONTROL_TOOL_NAMES = ("list_mcp_tools", "load_tool", "unload_tool")
+
+_PROVIDER_SAFE_TOOL_NAME_RE = re.compile(r"^[A-Za-z0-9_-]+$")
+_TOOL_NAME_PREFIX_RE = re.compile(r"^[A-Za-z0-9](?:[A-Za-z0-9_-]*[A-Za-z0-9])?$")
+
+
+def validate_mcp_exposed_tool_name(value: object) -> str | None:
+    """Return an error when a final MCP tool name is not provider-portable."""
+    if not isinstance(value, str):
+        return "tool name must be a string."
+    if not value:
+        return "tool name must not be empty."
+    if len(value) > MAX_MCP_EXPOSED_TOOL_NAME_LENGTH:
+        return f"tool name {value!r} is {len(value)} characters; the maximum is {MAX_MCP_EXPOSED_TOOL_NAME_LENGTH}."
+    if not _PROVIDER_SAFE_TOOL_NAME_RE.fullmatch(value):
+        return f"tool name {value!r} may contain only letters, numbers, underscores, and hyphens."
+    return None
+
+
+def validate_mcp_tool_name_prefix(
+    value: object,
+    *,
+    generated_suffixes: Collection[str] = (),
+) -> str | None:
+    """Return a validation error for an MCP tool-name prefix, or ``None`` if valid."""
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        return "tool name prefix must be a string."
+    if not value:
+        return None
+    if value != value.strip():
+        return "tool name prefix must not include leading or trailing whitespace."
+    if not _TOOL_NAME_PREFIX_RE.fullmatch(value):
+        return (
+            "tool name prefix may contain only letters, numbers, underscores, and hyphens, "
+            "and must start and end with a letter or number."
+        )
+    if len(value) > MAX_MCP_EXPOSED_TOOL_NAME_LENGTH:
+        return f"tool name prefix is {len(value)} characters; the maximum is {MAX_MCP_EXPOSED_TOOL_NAME_LENGTH}."
+    for suffix in generated_suffixes:
+        generated_name = f"{value}_{suffix}"
+        if error := validate_mcp_exposed_tool_name(generated_name):
+            return f"tool name prefix produces an invalid generated control: {error} Shorten Tool Name Prefix."
+    return None
+
+
+def validate_mcp_tool_loading_policy(
+    *,
+    allowed_tools: list[str] | None,
+    use_progressive_disclosure: bool,
+    always_load: list[str],
+) -> list[str]:
+    """Validate the catalog -> loading strategy -> initial subset hierarchy."""
+    errors: list[str] = []
+    if always_load and not use_progressive_disclosure:
+        errors.append("always_load requires use_progressive_disclosure=true.")
+    if allowed_tools == [] and use_progressive_disclosure:
+        errors.append("progressive disclosure requires at least one permitted tool.")
+    if allowed_tools is not None:
+        outside_scope = [name for name in always_load if name not in set(allowed_tools)]
+        if outside_scope:
+            errors.append(f"always_load tools must also appear in allowed_tools: {', '.join(outside_scope)}.")
+    return errors

chrys/service/mutations/__init__.py

@@ -0,0 +1,84 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""File mutation tracking for diff and rollback support.
+
+Tracks all file system changes made by agent tools (write_file, edit_file,
+shell commands) and stores original file snapshots in the session directory
+for potential rollback.
+
+**Concepts**
+
+- **Snapshot**: A copy of a file's content taken *before* the first mutation
+  within an execution period.  Content-addressable blobs stored under the session
+  directory.  A file is snapshotted at most once per period.  Blob writes are
+  gated by a ``SnapshotPolicy`` — oversized (default > 50 MiB) or binary
+  file contents are not backed up (the mutation record remains, marked
+  with a ``SnapshotSkipReason``; no diff rendering / rollback for it).
+- **Mutation**: A record of a single file operation (create / modify / delete
+  / move) linked to the originating tool call and execution period.
+- **Period**: ``TurnMutations`` belongs to a Chat Turn; ``RunMutations``
+  belongs to one Workflow Run (all nodes and retries). Every execution is
+  recorded, including empty ones. Typed scopes carry real execution IDs;
+  ``period_index`` orders snapshots and is never a public Run selector.
+- **Rollback**: File plan construction is shared. Chat rollback also restores
+  its conversation; a Workflow file plan never restores an Agent or scheduler.
+
+**Storage layout**::
+
+    {session_dir}/
+    ├── session.json                  # gains "chrys_mutations" key
+    └── mutations/
+        └── {sha256_hex}             # content-addressable file blobs
+
+**Integration points** (future implementation):
+
+1. **Engine / Executor**: ``tracker.start_turn(turn_id)`` at the
+   start of each ``agent.run()`` cycle.
+2. **filesystem.py**: ``tracker.record(path, op, source, call_id)``
+   BEFORE performing write_file / edit_file.
+3. **shell.py**: ``WorkspaceScanner`` before/after execution, then
+   ``tracker.record()`` for each detected change.
+4. **SessionPersistence**: ``tracker.serialize()`` / ``deserialize()``
+   into ``state["chrys_mutations"]``.
+5. **Session deletion**: ``tracker.clear()`` to remove all blobs.
+"""
+
+from chrys.service.mutations.detector import ShellMutationDetector
+from chrys.service.mutations.git_calibrator import GitDiffCalibrator, ImplicitChange
+from chrys.service.mutations.scanner import DEFAULT_EXCLUDES, FileStat, GitignoreFilter, WorkspaceScanner
+from chrys.service.mutations.store import BlobSaveResult, SnapshotPolicy, SnapshotStore
+from chrys.service.mutations.tracker import MutationTracker
+from chrys.service.mutations.types import (
+    FileMutation,
+    FileSnapshot,
+    MutationLog,
+    MutationOp,
+    MutationPeriod,
+    MutationSource,
+    RunMutations,
+    SnapshotSkipReason,
+    TurnMutations,
+)
+
+__all__ = [
+    "DEFAULT_EXCLUDES",
+    "BlobSaveResult",
+    "FileMutation",
+    "FileSnapshot",
+    "FileStat",
+    "GitDiffCalibrator",
+    "GitignoreFilter",
+    "ImplicitChange",
+    "MutationLog",
+    "MutationOp",
+    "MutationPeriod",
+    "MutationSource",
+    "MutationTracker",
+    "RunMutations",
+    "ShellMutationDetector",
+    "SnapshotPolicy",
+    "SnapshotSkipReason",
+    "SnapshotStore",
+    "TurnMutations",
+    "WorkspaceScanner",
+]