iCode-TUI 0.29.1__py3-none-any.whl

chrys/foundation/tool_execution_stamp.py

@@ -0,0 +1,184 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Compact, persistent metadata for one completed tool invocation."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+from collections.abc import Mapping, MutableMapping
+from dataclasses import asdict, is_dataclass
+from datetime import date, datetime
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import BaseModel
+
+logger = logging.getLogger(__name__)
+
+EXECUTION_STAMP_KEY = "_exec_stamp"
+"""Per-result ``additional_properties`` key for effective invocation metadata."""
+
+EFFECTIVE_ARGS_MAX_CHARS = 2_048
+"""Maximum stored canonical argument characters; longer values are middle-truncated."""
+
+EXECUTION_STAMP_DIGEST_HEX_CHARS = 16
+"""Number of leading SHA-256 hex characters stored for the full argument payload."""
+
+ExecutionOutcome = Literal["ok", "error"]
+
+
+def write_execution_stamp(
+    metadata: MutableMapping[str, Any],
+    arguments: Any,
+    *,
+    outcome: ExecutionOutcome,
+    error_kind: str | None = None,
+) -> None:
+    """Write the canonical execution stamp for one completed invocation."""
+    try:
+        stamp = build_execution_stamp(
+            arguments,
+            outcome=outcome,
+            error_kind=error_kind,
+        )
+    except Exception:
+        # Execution stamps are observability/durability metadata. A custom
+        # typed argument that cannot be represented must never turn an
+        # otherwise successful tool invocation into a tool failure.
+        logger.debug("Failed to serialize tool execution stamp", exc_info=True)
+        return
+    metadata[EXECUTION_STAMP_KEY] = stamp
+
+
+def build_execution_stamp(
+    arguments: Any,
+    *,
+    outcome: ExecutionOutcome,
+    error_kind: str | None = None,
+) -> dict[str, str]:
+    """Return a compact stamp whose digest covers the uncapped canonical arguments."""
+    serialized = canonicalize_effective_arguments(arguments)
+    stamp = {
+        "effective_args_digest": hashlib.sha256(serialized.encode("utf-8", errors="surrogatepass")).hexdigest()[
+            :EXECUTION_STAMP_DIGEST_HEX_CHARS
+        ],
+        "effective_args": _middle_truncate(serialized, EFFECTIVE_ARGS_MAX_CHARS),
+        "outcome": outcome,
+    }
+    if error_kind:
+        stamp["error_kind"] = error_kind
+    return stamp
+
+
+def canonicalize_effective_arguments(arguments: Any) -> str:
+    """Serialize JSON-like effective arguments deterministically and compactly."""
+    payload = arguments.model_dump(mode="json") if isinstance(arguments, BaseModel) else arguments
+    return json.dumps(
+        _normalize_json_containers(payload),
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+        default=_json_default,
+    )
+
+
+def _normalize_json_containers(value: Any) -> Any:
+    """Normalize typed container shapes before deterministic JSON encoding.
+
+    Pydantic validation can turn JSON object keys into typed Python values
+    such as :class:`date`. ``json.dumps(default=...)`` never applies its
+    default handler to mapping keys, so normalize those keys explicitly.
+    If normalization would collapse distinct keys, preserve the mapping as
+    sorted key/value pairs instead of dropping data.
+    """
+    if isinstance(value, BaseModel):
+        return _normalize_json_containers(value.model_dump(mode="json"))
+    if is_dataclass(value) and not isinstance(value, type):
+        return _normalize_json_containers(asdict(value))
+    if isinstance(value, Mapping):
+        normalized_items = [
+            (_canonical_mapping_key(key), _normalize_json_containers(nested)) for key, nested in value.items()
+        ]
+        keys = [key for key, _nested in normalized_items]
+        if len(keys) == len(set(keys)):
+            return dict(normalized_items)
+        items = [[_normalize_json_containers(key), _normalize_json_containers(nested)] for key, nested in value.items()]
+        items.sort(key=_canonical_sort_key)
+        return {"__mapping_items__": items}
+    if isinstance(value, list | tuple):
+        return [_normalize_json_containers(item) for item in value]
+    if isinstance(value, set | frozenset):
+        items = [_normalize_json_containers(item) for item in value]
+        items.sort(key=_canonical_sort_key)
+        return items
+    return value
+
+
+def _canonical_mapping_key(value: Any) -> str:
+    """Render one Python mapping key as its stable JSON-object key."""
+    if isinstance(value, str):
+        return value
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int | float):
+        return json.dumps(value, ensure_ascii=False)
+    converted = _json_default(value)
+    if isinstance(converted, str):
+        return converted
+    return _canonical_sort_key(_normalize_json_containers(converted))
+
+
+def _canonical_sort_key(value: Any) -> str:
+    """Return a deterministic ordering key for normalized container values."""
+    return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"), default=_json_default)
+
+
+def execution_stamp_from_metadata(metadata: Mapping[str, Any]) -> dict[str, str] | None:
+    """Return a validated shallow copy of a stored execution stamp."""
+    value = metadata.get(EXECUTION_STAMP_KEY)
+    if not isinstance(value, Mapping):
+        return None
+    digest = value.get("effective_args_digest")
+    arguments = value.get("effective_args")
+    outcome = value.get("outcome")
+    if not isinstance(digest, str) or not isinstance(arguments, str) or outcome not in {"ok", "error"}:
+        return None
+    stamp = {
+        "effective_args_digest": digest,
+        "effective_args": arguments,
+        "outcome": outcome,
+    }
+    error_kind = value.get("error_kind")
+    if isinstance(error_kind, str) and error_kind:
+        stamp["error_kind"] = error_kind
+    return stamp
+
+
+def _middle_truncate(value: str, max_chars: int) -> str:
+    if len(value) <= max_chars:
+        return value
+    marker = "…"
+    available = max_chars - len(marker)
+    left = (available + 1) // 2
+    right = available - left
+    return f"{value[:left]}{marker}{value[len(value) - right :]}"
+
+
+def _json_default(value: Any) -> Any:
+    if isinstance(value, BaseModel):
+        return value.model_dump(mode="json")
+    if is_dataclass(value) and not isinstance(value, type):
+        return asdict(value)
+    if isinstance(value, bytes):
+        return value.decode("utf-8", errors="replace")
+    if isinstance(value, (date, datetime)):
+        return value.isoformat()
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, (set, frozenset)):
+        return sorted(value, key=repr)
+    return str(value)

chrys/foundation/tool_invocation_order.py

@@ -0,0 +1,48 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Single-producer tool invocation ordinal.
+
+The kernel tool loop is the sole authoritative producer: it stamps every
+non-informational ``function_call`` content of a run attempt with a 0-based
+ordinal in model emission order, at response arrival — before the dispatch
+filter, tool lookup, and argument validation. Calls that never reach the
+middleware pipeline (invalid arguments, unknown tools, duplicate ids, no-tools
+batches) still consume ordinals, so persisted numbering and pipeline numbering
+can never diverge.
+
+The same key carries the ordinal in two mappings with one meaning:
+
+- ``Content.additional_properties`` on the assistant ``function_call``
+  (persisted to session.json; consumers such as approval-decision
+  persistence read it back instead of counting positions), and
+- ``FunctionInvocationContext.metadata`` (runtime carriage; event/approval
+  middleware read it via their existing accessors).
+
+Consumers must treat a missing stamp as "never order-match" (fail closed),
+not as "count for yourself".
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Final
+
+TOOL_INVOCATION_ORDER_KEY: Final[str] = "_chrys_tool_invocation_order"
+"""Current-run tool invocation ordinal (see module docstring)."""
+
+
+def read_tool_invocation_order(mapping: object) -> int | None:
+    """Return the stamped invocation ordinal from a metadata mapping, if any."""
+    if not isinstance(mapping, Mapping):
+        return None
+    raw = mapping.get(TOOL_INVOCATION_ORDER_KEY)
+    if isinstance(raw, bool):
+        return None
+    if isinstance(raw, int):
+        return raw
+    if isinstance(raw, str):
+        try:
+            return int(raw)
+        except ValueError:
+            return None
+    return None

chrys/foundation/tool_kinds.py

@@ -0,0 +1,102 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Canonical Chrys tool-kind vocabulary and out-of-band kind channel."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Final
+
+logger = logging.getLogger(__name__)
+
+KIND_SHELL: Final[str] = "shell"
+KIND_FILESYSTEM_READ: Final[str] = "filesystem.read"
+KIND_FILESYSTEM_WRITE: Final[str] = "filesystem.write"
+KIND_SEARCH: Final[str] = "search"
+KIND_WEB_SEARCH: Final[str] = "web_search"
+KIND_WEB_FETCH: Final[str] = "web_fetch"
+KIND_ASK_USER: Final[str] = "ask_user"
+KIND_SLEEP: Final[str] = "sleep"
+KIND_SUB_AGENT: Final[str] = "sub_agent"
+KIND_MCP: Final[str] = "mcp"
+KIND_DOC_CONVERTER: Final[str] = "doc_converter"
+KIND_SKILL: Final[str] = "skill"
+KIND_CONTEXT: Final[str] = "context"
+KIND_TODO: Final[str] = "todo"
+
+# Canonical set of Chrys tool kinds - the form shared by YAML, hook matchers,
+# approval-override keys and runtime events.
+TOOL_KINDS: Final[frozenset[str]] = frozenset(
+    {
+        KIND_SHELL,
+        KIND_FILESYSTEM_READ,
+        KIND_FILESYSTEM_WRITE,
+        KIND_SEARCH,
+        KIND_WEB_SEARCH,
+        KIND_WEB_FETCH,
+        KIND_ASK_USER,
+        KIND_SLEEP,
+        KIND_SUB_AGENT,
+        KIND_MCP,
+        KIND_DOC_CONVERTER,
+        KIND_SKILL,
+        KIND_CONTEXT,
+        KIND_TODO,
+    }
+)
+
+TOOL_CALL_KIND_METADATA_KEY: Final[str] = "_chrys_tool_kind"
+"""Structured tool kind persisted on assistant ``function_call`` contents.
+
+Lives at the foundation layer so the kernel tool loop can stamp it on
+calls that never reach the service-layer middleware (pre-pipeline argument
+validation failures); ``chrys.service.session.message_metadata`` re-exports
+it for existing importers.
+"""
+
+_KIND_ATTR: Final[str] = "chrys_kind"
+
+# Pre-P1 runtime kinds were namespaced (``chrys.shell``); the deleted
+# YAML<->runtime conversion layer also accepted that form directly in config.
+_LEGACY_KIND_PREFIX: Final[str] = "chrys."
+
+
+def strip_legacy_kind_prefix(value: str, *, allow_tool_suffix: bool = False, source: str = "") -> str:
+    """Strip the legacy ``chrys.`` prefix from a config-supplied kind, warning once per call.
+
+    Bounded compat for pre-P1 YAML: only values that were *meaningful* under
+    the old prefixed scheme are rewritten:
+
+    - ``chrys.<known kind>`` (``chrys.shell`` -> ``shell``);
+    - with ``allow_tool_suffix=True``, ``chrys.<known kind>.<tool>`` too
+      (approval-override keys; ``chrys.filesystem.write.write_file`` ->
+      ``filesystem.write.write_file``).
+
+    Anything else (bare values, ``chrys.``-prefixed strings that never matched
+    a kind - possibly literal tool names) passes through unchanged.
+    """
+    if not value.startswith(_LEGACY_KIND_PREFIX):
+        return value
+    bare = value[len(_LEGACY_KIND_PREFIX) :]
+    recognized = bare in TOOL_KINDS or (
+        allow_tool_suffix and any(bare.startswith(f"{kind}.") and len(bare) > len(kind) + 1 for kind in TOOL_KINDS)
+    )
+    if not recognized:
+        return value
+    logger.warning(
+        "Legacy tool-kind value %r in %s - the 'chrys.' runtime prefix was removed; use %r.",
+        value,
+        source or "config",
+        bare,
+    )
+    return bare
+
+
+def set_tool_kind(tool: Any, kind: str) -> None:
+    """Classify *tool* with a Chrys kind, out of band."""
+    setattr(tool, _KIND_ATTR, kind)
+
+
+def get_tool_kind(tool: Any) -> str | None:
+    """Return the Chrys kind of *tool*, or ``None`` when unclassified."""
+    return getattr(tool, _KIND_ATTR, None)

chrys/foundation/tool_result_metadata.py

@@ -0,0 +1,287 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Shared keys and legacy text helpers for tool-result status."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from contextvars import ContextVar
+from typing import Any
+
+from chrys.foundation.hosted_tools import HostedToolStatus, normalize_hosted_tool_status
+from chrys.foundation.tool_kinds import (
+    KIND_ASK_USER,
+    KIND_CONTEXT,
+    KIND_DOC_CONVERTER,
+    KIND_FILESYSTEM_READ,
+    KIND_FILESYSTEM_WRITE,
+    KIND_SEARCH,
+    KIND_SHELL,
+    KIND_SKILL,
+    KIND_SLEEP,
+    KIND_SUB_AGENT,
+    KIND_WEB_FETCH,
+    KIND_WEB_SEARCH,
+)
+
+tool_payload_observation: ContextVar[dict[str, object] | None] = ContextVar("tool_payload_observation", default=None)
+"""Trajectory-only buffer for the active tool call's payload facts (truncation, spill artifact).
+
+Nothing here is persisted on the result; the tool event middleware folds it
+into ``tool.payload.observed``. It lives at the foundation layer because the
+kernel's own result ceiling is the last thing to bound a result, and its
+truncation would otherwise go unobserved.
+"""
+
+
+def record_payload_truncation(
+    original_text: str,
+    *,
+    original_bytes: int | None = None,
+    artifact_name: str | None = None,
+) -> None:
+    """Note that the active tool call's output was bounded before reaching the model.
+
+    *original_bytes* stands in for *original_text*'s size when the tool saw
+    more output than it kept.
+    """
+    observation = tool_payload_observation.get(None)
+    if observation is None:
+        return
+    if original_bytes is None:
+        original_bytes = len(original_text.encode("utf-8", errors="backslashreplace"))
+    # First writer wins the size: a later bounding pass only ever sees text
+    # that was already shortened, and the reader wants what the tool produced.
+    observation.setdefault("original_bytes", original_bytes)
+    observation["truncated"] = True
+    if artifact_name:
+        observation["artifact_id"] = artifact_name
+
+
+TOOL_RESULT_METADATA_KEY = "_chrys_tool_result_metadata"
+"""Structured renderer metadata persisted on ``function_result`` contents.
+
+Lives at the foundation layer so the kernel tool loop can fold the dict the
+event middleware carried in ``FunctionInvocationContext.metadata`` (same key,
+same meaning) into the result content at construction — the only moment the
+result's identity is unambiguous.
+"""
+
+TOOL_ERRORED_METADATA_KEY = "errored"
+"""True when the tool invocation failed outside normal tool-result semantics."""
+
+TOOL_FAILED_METADATA_KEY = "failed"
+"""True when a tool returned a normal, structured failure result."""
+
+TOOL_INTERRUPTED_METADATA_KEY = "interrupted"
+"""True when cancellation answered an in-flight invocation."""
+
+TOOL_POST_PROCESSING_INTERRUPTED_METADATA_KEY = "interrupted_post_processing"
+"""True when the tool returned but cancellation interrupted result processing."""
+
+TOOL_ERROR_KIND_METADATA_KEY = "tool_error_kind"
+"""Stable category for a structured tool failure."""
+
+TOOL_ERROR_MESSAGE_METADATA_KEY = "tool_error_message"
+"""Human-readable structured tool failure message, without the ``Error:`` prefix."""
+
+TOOL_FAILURE_TEXT_SYNTHESIZED_METADATA_KEY = "failure_text_synthesized"
+"""True when Chrys synthesized a provider-hosted tool's fallback failure text."""
+
+TOOL_ERROR_CODE_METADATA_KEY = "tool_error_code"
+"""Optional provider/tool-specific structured error code."""
+
+TOOL_ERROR_RETRYABLE_METADATA_KEY = "tool_error_retryable"
+"""Optional structured retryability hint for a tool failure."""
+
+TOOL_ERROR_DETAILS_METADATA_KEY = "tool_error_details"
+"""Optional JSON-safe structured details for a tool failure."""
+
+PROCESS_EXIT_CODE_METADATA_KEY = "process_exit_code"
+"""Integer process exit code for generic subprocess-backed tool results."""
+
+PROCESS_TIMED_OUT_METADATA_KEY = "process_timed_out"
+"""True when a generic subprocess-backed tool result timed out."""
+
+PROCESS_TIMEOUT_SECONDS_METADATA_KEY = "process_timeout_seconds"
+"""Configured timeout, in seconds, for generic subprocess-backed tool results."""
+
+SHELL_EXIT_CODE_METADATA_KEY = "shell_exit_code"
+"""Integer process exit code for shell tool results."""
+
+SHELL_TIMED_OUT_METADATA_KEY = "shell_timed_out"
+"""True when the shell command was killed by Chrys timeout handling."""
+
+SHELL_TIMEOUT_SECONDS_METADATA_KEY = "shell_timeout_seconds"
+"""Configured timeout, in seconds, for timed-out shell commands."""
+
+PARTIAL_OUTPUT_LABEL = "[partial output]"
+"""The line that opens what a timed-out command or script printed, under its error line."""
+
+WEB_SEARCH_METADATA_KEY = "web_search"
+"""Provider id and result sources (``title`` and ``url`` only) for the web search card."""
+
+WEB_SEARCH_TITLE_MAX_CHARS = 300
+"""Longest source title the web search card shows, and so the longest one recorded."""
+
+WEB_FETCH_FINAL_URL_METADATA_KEY = "web_fetch_final_url"
+"""The URL a web fetch finally read, after same-site redirects, for the web fetch card."""
+
+_RESULT_EXIT_CODE_SUFFIX_RE = re.compile(r"\n?\[exit_code:\s*(-?\d+)\][ \t\r\n]*$")
+
+ERROR_TEXT_TOOL_KINDS = frozenset(
+    {
+        KIND_ASK_USER,
+        KIND_CONTEXT,
+        KIND_DOC_CONVERTER,
+        KIND_FILESYSTEM_READ,
+        KIND_FILESYSTEM_WRITE,
+        KIND_SEARCH,
+        KIND_WEB_SEARCH,
+        KIND_WEB_FETCH,
+        KIND_SHELL,
+        KIND_SKILL,
+        KIND_SLEEP,
+        KIND_SUB_AGENT,
+    }
+)
+"""Tool kinds where legacy ``Error:`` result text may indicate failure.
+
+``KIND_SKILL`` / ``KIND_CONTEXT`` membership preserves failure-detection
+parity: their tools sit in ``LEGACY_ERROR_TEXT_TOOL_NAMES`` (except
+``list_compressed_contexts``), and the name fallback in
+:func:`legacy_error_text_applies` only fires while the persisted kind is
+empty — without these entries, stamping the new kinds would silently stop
+treating legacy ``Error:`` text as failure on replay.
+"""
+
+LEGACY_ERROR_TEXT_TOOL_NAMES = frozenset(
+    {
+        "compress_context",
+        "convert_document",
+        "edit_file",
+        "execute",
+        "glob",
+        "grep",
+        "load_skill",
+        "ask_user",
+        "bash",
+        "cmd",
+        "csh",
+        "dash",
+        "fish",
+        "git_bash",
+        "ksh",
+        "list_workspace_dirs",
+        "powershell",
+        "pwsh",
+        "read_file",
+        "read_skill_resource",
+        "recall_context",
+        "run_skill_script",
+        "sh",
+        "sleep",
+        "tcsh",
+        "view_image",
+        "write_file",
+        "zsh",
+    }
+)
+"""Known Chrys-owned tool names kept for old session replay compatibility."""
+
+REJECTION_ERROR_KINDS = frozenset({"approval_rejected", "hook_denied"})
+"""Structured failure kinds that represent rejected tool execution."""
+
+
+def legacy_error_text_applies(tool_kind: str = "", tool_name: str = "") -> bool:
+    """Return true when consumers may use legacy ``Error:`` text as a failure signal."""
+    return tool_kind in ERROR_TEXT_TOOL_KINDS or (not tool_kind and tool_name in LEGACY_ERROR_TEXT_TOOL_NAMES)
+
+
+def result_text_exit_code(result: str) -> int | None:
+    """Return a shell-style trailing exit code, when one is present."""
+    match = _RESULT_EXIT_CODE_SUFFIX_RE.search(result)
+    if match is None:
+        return None
+    return int(match.group(1))
+
+
+def result_text_without_exit_code(result: str) -> str:
+    """Return result text with a trailing ``[exit_code: N]`` suffix removed."""
+    return _RESULT_EXIT_CODE_SUFFIX_RE.sub("", result).rstrip("\n")
+
+
+def shell_exit_code_from_metadata(metadata: Mapping[str, Any] | None) -> int | None:
+    """Return a structured shell exit code, when metadata carries one."""
+    return _int_metadata_value(metadata, SHELL_EXIT_CODE_METADATA_KEY)
+
+
+def process_exit_code_from_metadata(metadata: Mapping[str, Any] | None) -> int | None:
+    """Return a structured generic process exit code, when metadata carries one."""
+    return _int_metadata_value(metadata, PROCESS_EXIT_CODE_METADATA_KEY)
+
+
+def shell_timed_out_from_metadata(metadata: Mapping[str, Any] | None) -> bool:
+    """Return true when structured metadata says the shell command timed out."""
+    return _bool_metadata_true(metadata, SHELL_TIMED_OUT_METADATA_KEY)
+
+
+def process_timed_out_from_metadata(metadata: Mapping[str, Any] | None) -> bool:
+    """Return true when structured metadata says a generic process timed out."""
+    return _bool_metadata_true(metadata, PROCESS_TIMED_OUT_METADATA_KEY)
+
+
+def tool_result_metadata_is_rejected(metadata: Mapping[str, Any] | None) -> bool:
+    """Return true when structured metadata says tool execution was rejected."""
+    if not metadata:
+        return False
+    if metadata.get("approval") == "user_rejected":
+        return True
+    return metadata.get(TOOL_ERROR_KIND_METADATA_KEY) in REJECTION_ERROR_KINDS
+
+
+def tool_result_metadata_failure_state(metadata: Mapping[str, Any] | None) -> bool | None:
+    """Return structured failure state, or None when metadata has no answer."""
+    if not metadata:
+        return None
+    if metadata.get(TOOL_ERRORED_METADATA_KEY) is True:
+        return True
+    if tool_result_metadata_is_rejected(metadata):
+        return True
+    failed = metadata.get(TOOL_FAILED_METADATA_KEY)
+    if failed is True:
+        return True
+    if process_timed_out_from_metadata(metadata) or shell_timed_out_from_metadata(metadata):
+        return True
+    exit_code = process_exit_code_from_metadata(metadata)
+    if exit_code is None:
+        exit_code = shell_exit_code_from_metadata(metadata)
+    if exit_code is not None:
+        return exit_code != 0
+    if failed is False:
+        return False
+    return None
+
+
+def _int_metadata_value(metadata: Mapping[str, Any] | None, key: str) -> int | None:
+    if not metadata:
+        return None
+    value = metadata.get(key)
+    if isinstance(value, bool):
+        return None
+    return value if isinstance(value, int) else None
+
+
+def _bool_metadata_true(metadata: Mapping[str, Any] | None, key: str) -> bool:
+    if not metadata:
+        return False
+    return metadata.get(key) is True
+
+
+def canonical_tool_result_status(provider_status: str | None, metadata: Mapping[str, Any] | None) -> str:
+    """Prefer a terminal provider status, then structured tool-result failure metadata."""
+    status = normalize_hosted_tool_status(provider_status)
+    if status in {HostedToolStatus.COMPLETED, HostedToolStatus.FAILED, HostedToolStatus.INTERRUPTED}:
+        return status.value
+    return "failed" if tool_result_metadata_failure_state(metadata) is True else "completed"

chrys/foundation/trajectory/__init__.py

@@ -0,0 +1,10 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Append-only trajectory event log: envelope, writer, reader, and helpers.
+
+``session.json`` holds the conversation truth; ``<session>/trajectory/events.jsonl``
+holds the execution truth — one content-minimized JSON event per line, written
+through a single per-session writer with written-ack semantics. This package is
+the foundation-tier contract: every module here depends on the standard library
+and sibling foundation helpers only.
+"""