iCode-TUI 0.29.1__py3-none-any.whl

chrys/service/tools/spill.py

@@ -0,0 +1,218 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Session-local spill files for truncated tool output."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import stat
+from collections.abc import Callable, Sequence
+from contextlib import suppress
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+from chrys.foundation.platform import get_platform
+from chrys.foundation.platform.files import atomic_write_owner_only_bytes, secure_unlink_owner_verified
+from chrys.foundation.platform.output_capture import CapturedOutput, capture_limit_footer
+from chrys.foundation.text.tokenizer import MixedLanguageTokenizer
+from chrys.foundation.text.tool_output import truncate_output
+from chrys.foundation.tool_result_metadata import (
+    record_payload_truncation,
+    result_text_exit_code,
+    result_text_without_exit_code,
+)
+from chrys.kernel.tools import SyncToolCancelledAfterCompletion
+
+logger = logging.getLogger(__name__)
+
+TOOL_RESULTS_DIR_NAME = "tool_results"
+
+_tokenizer = MixedLanguageTokenizer()
+
+_MARKER_TOKENS = 20
+"""Room for a truncation marker, whose counts stay under nine digits for any output a capture keeps."""
+
+
+@dataclass(frozen=True, slots=True)
+class SpillInfo:
+    """A successfully written spill and its model-facing notice."""
+
+    path: Path
+    notice: str
+
+
+def discard_spill(info: SpillInfo) -> None:
+    """Best-effort cleanup when a defensive truncation path loses its notice."""
+    if info.path.exists() and not secure_unlink_owner_verified(info.path):
+        logger.warning("Failed to discard unreferenced tool-output spill %s", info.path)
+
+
+def _ensure_owner_only_directory(path: Path) -> None:
+    """Create the spill directory privately and tighten existing POSIX modes."""
+    path.mkdir(mode=0o700, parents=True, exist_ok=True)
+    if get_platform().is_windows:
+        return
+
+    flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_CLOEXEC", 0)
+    flags |= getattr(os, "O_NOFOLLOW", 0)
+    fd = os.open(path, flags)
+    try:
+        info = os.fstat(fd)
+        if not stat.S_ISDIR(info.st_mode):
+            raise OSError("Tool-result spill path is not a directory.")
+        os.fchmod(fd, 0o700)
+    finally:
+        os.close(fd)
+
+
+def format_spill_notice(path: Path, text: str, *, kept_only: bool = False) -> str:
+    """Format the bounded-result notice for a spill at *path*.
+
+    *kept_only* says the spill holds only what a bounded capture kept.
+    """
+    line_count = text.count("\n") + 1
+    token_count = _tokenizer.count_tokens(text)
+    saved = "Kept output" if kept_only else "Full output"
+    return (
+        f"[{saved} saved to: {path}\n"
+        f"{line_count} lines, ~{token_count} tokens. Use read_file or shell tools to inspect it.]"
+    )
+
+
+def _spill_fit_marker(text: str) -> str:
+    total_tokens = _tokenizer.count_tokens(text)
+    line_marker = f"[...truncated {len(text.splitlines())} lines (estimated {total_tokens} tokens total)...]"
+    char_marker = f"[...truncated ~{len(text)} chars (estimated {total_tokens} tokens total)...]"
+    return max((line_marker, char_marker), key=_tokenizer.count_tokens)
+
+
+def try_spill_text(
+    dir_path: Path | None,
+    prefix: str,
+    text: str,
+    budget: int,
+    reserved_footer: str = "",
+    *,
+    kept_only: bool = False,
+) -> SpillInfo | None:
+    """Write *text* under the session if its complete notice can fit."""
+    if dir_path is None:
+        record_payload_truncation(text)
+        return None
+
+    try:
+        canonical_dir = dir_path.resolve(strict=False)
+    except OSError, RuntimeError:
+        logger.warning("Failed to resolve tool-output spill directory %s", dir_path, exc_info=True)
+        record_payload_truncation(text)
+        return None
+
+    # Canonicalize only the trusted session directory.  The owned child path
+    # stays lexical so the secure writer can still reject a planted
+    # ``tool_results`` symlink/reparse point instead of following it.
+    path = canonical_dir / TOOL_RESULTS_DIR_NAME / f"{prefix}_{uuid4().hex[:8]}.txt"
+    notice = format_spill_notice(path, text, kept_only=kept_only)
+    footer = "\n".join(part for part in (_spill_fit_marker(text), reserved_footer, notice) if part)
+    if _tokenizer.count_tokens(footer) > budget:
+        record_payload_truncation(text)
+        return None
+
+    try:
+        _ensure_owner_only_directory(path.parent)
+        atomic_write_owner_only_bytes(path, text.encode("utf-8", errors="surrogateescape"))
+    except OSError:
+        logger.warning("Failed to spill truncated tool output to %s", path, exc_info=True)
+        with suppress(OSError):
+            secure_unlink_owner_verified(path)
+        record_payload_truncation(text)
+        return None
+    record_payload_truncation(text, artifact_name=path.name)
+    return SpillInfo(path=path, notice=notice)
+
+
+def _spill_and_truncate_text(
+    dir_path: Path | None, prefix: str, lead: str, text: str, budget: int, capture_footer: str
+) -> str:
+    body, footer = text, ""
+    if capture_footer:
+        # The capture's note goes right before a trailing exit code, which
+        # readers take from the very end of the result; a later bound that
+        # keeps the end of the result keeps both.
+        footer = f"\n{capture_footer}"
+        exit_code = result_text_exit_code(text)
+        if exit_code is not None:
+            body = result_text_without_exit_code(text)
+            footer += f"\n[exit_code: {exit_code}]"
+        whole = lead + body + footer
+        if truncate_output(whole, budget) == whole:
+            return whole
+    # Token counts are floored per text, so two texts can count one more
+    # together than apart.
+    reserved = sum(_tokenizer.count_tokens(part) + 1 for part in (lead, footer) if part)
+    if reserved + _MARKER_TOKENS > budget:
+        # No room for the output beside the error line and the note: keep the
+        # error line alone (without one, the output), cut in the middle if
+        # need be, then the note if it still fits.
+        room = budget - _tokenizer.count_tokens(footer) - 1
+        if not footer or room < 1:
+            footer, room = "", budget
+        return truncate_output(lead.partition("\n")[0] or body, room, head_ratio=1 / 2) + footer
+    budget -= reserved
+    info = try_spill_text(dir_path, prefix, text, budget, kept_only=bool(footer))
+    bounded = truncate_output(body, budget, truncation_suffix=info.notice if info else "")
+    if info is not None and info.notice not in bounded:
+        discard_spill(info)
+        bounded = truncate_output(body, budget)
+    return lead + bounded + footer
+
+
+async def run_spill_finalizer[T](function: Callable[..., T], /, *args: Any) -> T:
+    """Drain one threaded spill finalizer and carry its result through cancellation."""
+    worker = asyncio.create_task(asyncio.to_thread(function, *args))
+    try:
+        return await asyncio.shield(worker)
+    except asyncio.CancelledError:
+        while not worker.done():
+            try:
+                await asyncio.shield(worker)
+            except asyncio.CancelledError:
+                continue
+        try:
+            completed = worker.result()
+        except Exception as exc:
+            logger.warning("Tool-result spill finalizer failed while its caller was cancelled", exc_info=True)
+            raise asyncio.CancelledError from exc
+        raise SyncToolCancelledAfterCompletion(completed) from None
+
+
+async def bound_process_output(
+    dir_path: Path | None,
+    prefix: str,
+    text: str,
+    budget: int,
+    captures: Sequence[CapturedOutput] = (),
+    *,
+    lead: str = "",
+) -> str:
+    """Bound a finished process's result to *budget*, spilling it when it does not fit.
+
+    When *captures* dropped output, the trajectory records how many bytes the
+    process wrote and a note saying what was not kept comes last, or just
+    before a trailing exit code. *lead* (an error line, perhaps with a label
+    under it) opens the result whatever the bound keeps of *text*; when the
+    budget leaves *text* no room beside the lead and that note, only the
+    lead's first line is kept, cut short if need be. A spill holds only
+    *text*. The spill and the bounded view survive cancellation of the caller.
+    """
+    footer = capture_limit_footer(captures)
+    whole = lead + text
+    # Every character counts at least a quarter token, so a longer text cannot
+    # fit, and counting it here would hold the event loop.
+    if not footer and len(whole) <= 4 * (budget + 1) and truncate_output(whole, budget) == whole:
+        return whole
+    record_payload_truncation(whole, original_bytes=sum(capture.seen for capture in captures) if footer else None)
+    return await run_spill_finalizer(_spill_and_truncate_text, dir_path, prefix, lead, text, budget, footer)

chrys/service/tools/workspace_paths.py

@@ -0,0 +1,81 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Tool errors for a session working directory that no longer exists.
+
+The working directory can be deleted or moved outside the app while a turn
+runs. Tools then report that fact in one wording, which tells the model to
+stop and leave the choice of a new directory to the user, instead of a
+misleading "not found" about the shell, interpreter or file.
+"""
+
+from __future__ import annotations
+
+import os
+
+from chrys.foundation.branding import APP_DISPLAY_NAME
+from chrys.foundation.platform.paths import is_absolute_path
+from chrys.service.tools.result_metadata import tool_error
+from chrys.service.tools.session_artifacts import is_document_artifact_handle
+
+WORKING_DIR_MISSING_KIND = "working_dir_missing"
+
+
+def working_dir_missing_error(path: str) -> str:
+    """Return the model-visible error for a session working directory that is gone."""
+    return tool_error(
+        WORKING_DIR_MISSING_KIND,
+        f"working directory no longer exists — {path} (deleted or moved outside {APP_DISPLAY_NAME}). "
+        "Stop and tell the user; they need to choose another working directory.",
+        details={"cwd": path},
+    )
+
+
+def missing_base_cwd_error(raw_path: str, base_cwd: str | None) -> str | None:
+    """Return :func:`working_dir_missing_error` when *raw_path* depends on a missing *base_cwd*.
+
+    A relative path resolves against the working directory, and an absolute
+    path at or under it names a place inside it: using either would fail, or
+    a write would quietly recreate the deleted directory. Absolute paths
+    elsewhere and session artifact handles keep working.
+    """
+    if not base_cwd or os.path.isdir(base_cwd):
+        return None
+    if is_document_artifact_handle(raw_path):
+        return None
+    expanded = os.path.expanduser(raw_path.strip())
+    if (os.path.isabs(expanded) or is_absolute_path(expanded)) and not _is_within(expanded, base_cwd):
+        return None
+    return working_dir_missing_error(base_cwd)
+
+
+def _is_within(path: str, base: str) -> bool:
+    """Return whether absolute *path* is *base* or lies under it.
+
+    Compared as written and then with symlinks resolved, so another spelling
+    of the same place (a symlinked parent folder, macOS's ``/tmp`` and
+    ``/private/tmp``) also counts. Resolving follows the parts that still
+    exist and keeps the missing rest as written.
+    """
+    if _is_lexically_within(path, base):
+        return True
+    # A path absolute only under the other platform's rules names no place here.
+    if not (os.path.isabs(path) and os.path.isabs(base)):
+        return False
+    # ".." is removed first, as the tools' own resolver does, so a ".." after a
+    # symlink climbs the path as written rather than the link's target.
+    try:
+        return _is_lexically_within(os.path.realpath(os.path.normpath(path)), os.path.realpath(os.path.normpath(base)))
+    except OSError, ValueError:
+        return False
+
+
+def _is_lexically_within(path: str, base: str) -> bool:
+    # normpath, not abspath: abspath of a relative base would read the process
+    # cwd, which may be the deleted directory itself.
+    path_key = os.path.normcase(os.path.normpath(path))
+    base_key = os.path.normcase(os.path.normpath(base))
+    try:
+        return os.path.commonpath((path_key, base_key)) == base_key
+    except ValueError:
+        # Different drives, or an absolute and a relative path: never inside.
+        return False

chrys/service/trajectory/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Session-level trajectory recording: activation, lifecycle, deletion.
+
+The foundation package owns the file format and the writer; this package
+binds one writer to one live session (lease, recovery, coverage markers) and
+provides the engine-facing helpers (turn registry, fork prelude, tombstone
+deletion). Modules here are imported lazily by their callers — keep this
+``__init__`` free of imports so ``service.state.store`` and this package can
+depend on each other without a cycle.
+"""

chrys/service/trajectory/approvals.py

@@ -0,0 +1,201 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""``approval.requested`` / ``approval.resolved`` recording for the approval middleware."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from collections.abc import Mapping
+from typing import Any
+
+from chrys.foundation.trajectory.context import TrajectoryContext, current_trajectory
+from chrys.foundation.trajectory.envelope import MeasurementSource, measurement, utc_now_rfc3339
+from chrys.foundation.trajectory.event_types import EventType
+from chrys.foundation.trajectory.ids import new_analytics_id
+from chrys.foundation.trajectory.metadata import OPERATION_ID_KEY
+
+logger = logging.getLogger(__name__)
+
+
+class ApprovalDecision:
+    """``approval.resolved.decision``."""
+
+    APPROVED = "approved"
+    REJECTED = "rejected"
+    INTERRUPTED = "interrupted"
+
+
+class ApprovalDecider:
+    """``approval.resolved.decider``."""
+
+    USER = "user"
+    JUDGE = "judge"
+    NONE = "none"
+    """Nobody decided — the request was abandoned before an answer arrived."""
+
+
+class ApprovalTrace:
+    """One approval request: requested at publish, resolved once the decision lands."""
+
+    __slots__ = (
+        "_context",
+        "_generic_target",
+        "_request_id",
+        "_requested_committed",
+        "_requested_ns",
+        "_resolved",
+        "_target_operation_id",
+    )
+
+    def __init__(
+        self,
+        context: TrajectoryContext,
+        *,
+        target_operation_id: str | None,
+        generic_target: bool = False,
+    ) -> None:
+        self._context = context
+        # The log mints its own request id: the middleware's is a short-lived
+        # UI correlation token of a different shape, and nothing outside the
+        # in-flight request ever sees it. Both approval events carry this one,
+        # and ``target_tool_operation_id`` joins them to the call itself.
+        self._request_id = new_analytics_id()
+        self._target_operation_id = target_operation_id
+        self._generic_target = generic_target
+        self._requested_ns = time.monotonic_ns()
+        self._requested_committed = False
+        self._resolved = False
+
+    @property
+    def request_id(self) -> str:
+        """Stable approval interval identity for observer hook attribution."""
+        return self._request_id
+
+    @classmethod
+    def open(cls, invocation_metadata: Mapping[str, Any]) -> ApprovalTrace | None:
+        context = current_trajectory()
+        if context is None:
+            return None
+        target = invocation_metadata.get(OPERATION_ID_KEY)
+        return cls(context, target_operation_id=target if isinstance(target, str) else None)
+
+    @classmethod
+    def open_for_operation(
+        cls,
+        *,
+        context: TrajectoryContext | None,
+        target_operation_id: str | None,
+    ) -> ApprovalTrace | None:
+        """Open a non-tool-specific approval targeting an arbitrary boundary."""
+        if context is None:
+            return None
+        return cls(context, target_operation_id=target_operation_id, generic_target=True)
+
+    def _target_payload(self) -> dict[str, str | None]:
+        if self._target_operation_id is None:
+            return {}
+        key = "target_operation_id" if self._generic_target else "target_tool_operation_id"
+        return {key: self._target_operation_id}
+
+    def _parent(self) -> str | None:
+        if self._generic_target and self._target_operation_id is not None:
+            return self._target_operation_id
+        return self._context.innermost_model_operation_id
+
+    def _operation_id(self) -> str | None:
+        """Use the approval's own identity when its target is an arbitrary operation."""
+        if self._generic_target:
+            return self._request_id
+        return self._target_operation_id
+
+    async def requested(self, *, tool_name: str, approval_mode: str, approval_level: str) -> None:
+        payload: dict[str, Any] = {
+            "approval_request_id": self._request_id,
+            **self._target_payload(),
+            "approval_mode": approval_mode,
+            "approval_level": approval_level,
+            "tool_name": tool_name,
+            "requested_at": utc_now_rfc3339(),
+        }
+
+        def _commit(_sequence: int) -> Mapping[str, Any]:
+            self._requested_committed = True
+            return payload
+
+        try:
+            await self._context.sink.emit(
+                self._context.draft(
+                    EventType.APPROVAL_REQUESTED,
+                    operation_id=self._operation_id(),
+                    parent_operation_id=self._parent(),
+                    payload=payload,
+                ),
+                payload_factory=_commit,
+            )
+        except asyncio.CancelledError:
+            self.interrupted_soon(reason_code="cancelled")
+            raise
+        except Exception:
+            logger.debug("Trajectory approval.requested emit failed", exc_info=True)
+
+    def _resolved_draft(self, *, decision: str, decider: str, reason_code: str, arguments_modified: bool) -> Any:
+        payload: dict[str, Any] = {
+            "approval_request_id": self._request_id,
+            **self._target_payload(),
+            "decision": decision,
+            "decider": decider,
+            "reason_code": reason_code,
+            "arguments_modified": arguments_modified,
+            "resolved_at": utc_now_rfc3339(),
+            "wait_ms": max(0, (time.monotonic_ns() - self._requested_ns) // 1_000_000),
+        }
+        return self._context.draft(
+            EventType.APPROVAL_RESOLVED,
+            operation_id=self._operation_id(),
+            parent_operation_id=self._parent(),
+            payload=payload,
+            measurements={"/payload/wait_ms": measurement(MeasurementSource.MONOTONIC_CLOCK, method_version=1)},
+        )
+
+    async def resolved(self, *, approved: bool, decider: str, reason_code: str, arguments_modified: bool) -> None:
+        if self._resolved:
+            return
+        self._resolved = True
+        if not self._requested_committed:
+            return
+        draft = self._resolved_draft(
+            decision=ApprovalDecision.APPROVED if approved else ApprovalDecision.REJECTED,
+            decider=decider,
+            reason_code=reason_code,
+            arguments_modified=arguments_modified,
+        )
+        try:
+            await self._context.sink.emit(draft)
+        except Exception:
+            logger.debug("Trajectory approval.resolved emit failed", exc_info=True)
+
+    def interrupted_soon(self, *, reason_code: str = "interrupted") -> None:
+        """Close a request nobody answered (queued in order, ack not awaited).
+
+        The interrupt that abandons an approval also cancels the task waiting
+        on it, so the close cannot await an acknowledgement it would never be
+        allowed to receive — and a request with no resolution is a span the
+        reader could never close.
+        """
+        if self._resolved:
+            return
+        self._resolved = True
+        if not self._requested_committed:
+            return
+        draft = self._resolved_draft(
+            decision=ApprovalDecision.INTERRUPTED,
+            decider=ApprovalDecider.NONE,
+            reason_code=reason_code,
+            arguments_modified=False,
+        )
+        try:
+            self._context.sink.emit_soon(draft)
+        except Exception:
+            logger.debug("Trajectory approval.resolved emit failed", exc_info=True)