iCode-TUI 0.29.1__py3-none-any.whl

chrys/orchestration/invoker/child_compaction.py

@@ -0,0 +1,131 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Child compaction rollback and invocation-scoped hook and status reporting."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, cast
+
+from chrys.foundation.events.types import (
+    InvocationCompactionCommitted,
+    InvocationCompactionFinished,
+    InvocationCompactionStarted,
+    InvocationContextPressure,
+    InvocationRetryAttempt,
+)
+from chrys.service.hooks.events import HookEvent
+
+if TYPE_CHECKING:
+    from chrys.foundation.retry import RetryAttemptInfo
+    from chrys.orchestration.invoker.origin import BoundEmitter
+    from chrys.service.context.compaction import PreCompactInfo
+    from chrys.service.context.compaction.last_words import CompactionStatus
+    from chrys.service.context.compaction.last_words_state import DropRoundBreakerState
+    from chrys.service.context.compaction.strategy import CompactionRetrySnapshot, UnifiedContextStrategy
+    from chrys.service.hooks.manager import HookManager
+
+
+@dataclass(frozen=True, slots=True)
+class CompactionRollback:
+    strategy: UnifiedContextStrategy | None
+
+    def snapshot(self) -> object:
+        return self.strategy.snapshot_retry_state() if self.strategy is not None else None
+
+    def restore(self, state: object) -> None:
+        if self.strategy is not None and state is not None:
+            self.strategy.restore_retry_state(cast("CompactionRetrySnapshot", state))
+
+
+@dataclass(frozen=True, slots=True)
+class ChildCompactionEvents:
+    emitter: Callable[[], BoundEmitter]
+    """The publisher of the pass in flight, read once per report: a retried pass may publish as another attempt."""
+    name: str
+    tool_name: str
+    profile: str
+    workspace_cwd: str
+    hook_manager: HookManager | None
+
+    async def pre_compact(self, info: PreCompactInfo) -> None:
+        hooks = self.hook_manager
+        if hooks is None or not hooks.has_hooks_for(HookEvent.PRE_COMPACT):
+            return
+        await hooks.fire(
+            HookEvent.PRE_COMPACT,
+            {
+                "session_id": self.emitter().origin.session_id,
+                "profile": self.profile,
+                "cwd": self.workspace_cwd,
+                "trigger": info.trigger,
+                "usage_pct": info.usage_pct,
+                "tokens_before": info.tokens_before,
+                "sub_agent": {"name": self.name, "tool_name": self.tool_name},
+            },
+            target_operation_id=info.trajectory_operation_id,
+        )
+
+    async def context_pressure(self, reason: str, breaker: DropRoundBreakerState, budget: int) -> None:
+        emitter = self.emitter()
+        await emitter.publish(
+            InvocationContextPressure(
+                origin=emitter.origin,
+                reason=reason,
+                attempts=breaker.attempts,
+                side_call_tokens=breaker.side_call_tokens,
+                side_call_token_budget=budget,
+                source=emitter.origin.kind,
+                session_id=emitter.origin.session_id,
+            )
+        )
+
+    async def retry(self, info: RetryAttemptInfo) -> None:
+        emitter = self.emitter()
+        await emitter.publish(
+            InvocationRetryAttempt(
+                scope="compaction",
+                origin=emitter.origin,
+                agent_name=self.name,
+                message=f"LAST_WORDS compaction: {info.reason}",
+                attempt=info.attempt,
+                max_attempts=info.max_attempts,
+                delay_seconds=int(info.delay_seconds),
+                session_id=emitter.origin.session_id,
+            )
+        )
+
+    async def status(self, status: CompactionStatus) -> None:
+        emitter = self.emitter()
+        if status.stage == "started":
+            await emitter.publish(
+                InvocationCompactionStarted(
+                    origin=emitter.origin,
+                    agent_name=self.name,
+                    compaction_id=status.compaction_id,
+                    session_id=emitter.origin.session_id,
+                )
+            )
+        elif status.stage == "committed":
+            await emitter.publish(
+                InvocationCompactionCommitted(
+                    origin=emitter.origin,
+                    agent_name=self.name,
+                    compaction_id=status.compaction_id,
+                    session_id=emitter.origin.session_id,
+                )
+            )
+        else:
+            await emitter.publish(
+                InvocationCompactionFinished(
+                    origin=emitter.origin,
+                    agent_name=self.name,
+                    compaction_id=status.compaction_id,
+                    outcome=status.outcome,
+                    duration_ms=status.duration_ms,
+                    format_violation=status.format_violation,
+                    failure_reason=status.failure_reason,
+                    session_id=emitter.origin.session_id,
+                )
+            )

chrys/orchestration/invoker/child_history.py

@@ -0,0 +1,99 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""History recovery and storage decisions shared by child kernel callers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+from typing import TYPE_CHECKING, Any
+
+from chrys.foundation.models.history_markers import copy_reminder_record
+from chrys.foundation.models.turns import is_continuation_message
+from chrys.kernel import Message, resolve_storage_mode_and_handles
+from chrys.service.session.history import SessionHistoryManager, stamp_history_item_ids
+
+if TYPE_CHECKING:
+    from chrys.kernel import AgentSession, LoopRecorder
+    from chrys.kernel.client import BaseChatClient
+
+
+def service_storage_side(client: BaseChatClient, options: Mapping[str, Any] | None) -> bool:
+    """Resolve the client's storage policy without retaining provider handles."""
+    return resolve_storage_mode_and_handles(
+        options,
+        stores_by_default=client.STORES_BY_DEFAULT,
+        force_stateless=client.FORCES_STATELESS,
+    ).service_side
+
+
+def active_input_message(active_input: Sequence[Any]) -> Message | None:
+    """Return the single input message that can anchor recovered loop work."""
+    if len(active_input) != 1:
+        return None
+    item = active_input[0]
+    if isinstance(item, Message):
+        return item
+    if isinstance(item, str):
+        return Message("user", [item])
+    return None
+
+
+class ChildHistory:
+    """Read the session's current state each time, including after retry rollback."""
+
+    def __init__(self, session: AgentSession, recorder: LoopRecorder) -> None:
+        self.session = session
+        self.recorder = recorder
+
+    def state(self) -> dict[str, Any]:
+        state = self.session.state.setdefault("chrys_history", {})
+        if not isinstance(state, dict):
+            state = {}
+            self.session.state["chrys_history"] = state
+        return state
+
+    def messages(self) -> list[Any]:
+        state = self.state()
+        messages = state.setdefault("messages", [])
+        if not isinstance(messages, list):
+            messages = []
+            state["messages"] = messages
+        return messages
+
+    def repair_after_failure(self, active_input: Sequence[Any], pass_start_index: int) -> None:
+        """Keep completed local work and discard the failed service continuation."""
+        messages = self.messages()
+        if self.recorder.loop_messages:
+            input_message = active_input_message(active_input)
+            if input_message is not None and not messages:
+                messages.append(input_message)
+        manager = SessionHistoryManager()
+        state = self.state()
+        stamp_history_item_ids(state)
+        manager.bind(state)
+        manager.merge_loop_messages(self.recorder, insert_index=pass_start_index)
+        manager.trim_to_last_complete_tool_results()
+        self.session.service_session_id = None
+
+    def retry_input(self, seed: Callable[[], list[Any]]) -> list[Any]:
+        """Continue completed work, otherwise replay the seed without duplicating its anchor.
+
+        Synthetic continuation nudges cannot become the user anchor for this decision.
+        """
+        messages = self.messages()
+        user_idx = -1
+        for i in range(len(messages) - 1, -1, -1):
+            if messages[i].role == "user" and not is_continuation_message(messages[i]):
+                user_idx = i
+                break
+        if user_idx < 0:
+            return seed()
+        if any(messages[j].role in ("assistant", "tool") for j in range(user_idx + 1, len(messages))):
+            return []
+        anchor = messages.pop(user_idx)
+        seeded = seed()
+        # The seed rebuilds the anchor it replaces: it carries the reminders
+        # the anchor was sent with, so the replay re-renders them unchanged.
+        if len(seeded) == 1 and isinstance(seeded[0], Message):
+            copy_reminder_record(anchor.additional_properties, seeded[0].additional_properties)
+        return seeded

chrys/orchestration/invoker/contracts.py

@@ -0,0 +1,253 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Neutral resource-close contracts, independent of backend and caller shells."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+from dataclasses import dataclass
+from enum import Enum, StrEnum
+from typing import Protocol
+
+from chrys.foundation.models.invocations import InvocationOrigin, PassHandle
+from chrys.kernel import Content, Message
+
+from .evidence import PassEvidence
+
+
+class AbortCause(Enum):
+    """Why an owner asks an operation to converge."""
+
+    USER_CANCEL = "user_cancel"
+    CALLER_TIMEOUT = "caller_timeout"
+    RUN_TERMINAL = "run_terminal"
+    CASCADE = "cascade"
+    OWNER_CLOSE = "owner_close"
+
+
+class PreparedClosed(RuntimeError):
+    """An acquire or open was attempted after its owner started closing."""
+
+
+class OperationBinding(Protocol):
+    """A shell's synchronous close latch and its complete cleanup barrier.
+
+    The barrier includes the writer, parent commit, end hook and live controls;
+    an empty attempt-task slot alone does not mean that it has drained.
+    """
+
+    def request_close(self, cause: AbortCause) -> None: ...
+
+    @property
+    def drained(self) -> Awaitable[None]: ...
+
+
+type Unbind = Callable[[], None]
+
+
+class SubAgentStatus(Enum):
+    """Lifecycle state of a single sub-agent invocation."""
+
+    IDLE = "idle"
+    RUNNING = "running"
+    PAUSED = "paused"
+    COMPLETED = "completed"
+    ABORTED = "aborted"
+    CASCADE_ABORTED = "cascade_aborted"
+
+
+class SubAgentFailureReason(StrEnum):
+    """Persisted reason for a caller's manual decision boundary."""
+
+    STREAM_STALL = "stream_stall"
+    LAST_WORDS = "last_words"
+    FRAMEWORK_EXC = "framework_exc"
+    ACP_TRANSPORT = "acp_transport"
+
+
+class RunIntent(Enum):
+    FRESH = "fresh"
+    CONTINUE = "continue"
+    RETRY = "retry"
+
+
+class ContinuationCapability(Enum):
+    CONTINUE_HISTORY = "continue_history"
+    FRESH_SESSION = "fresh_session"
+
+
+class StopCause(Enum):
+    COMPLETED = "completed"
+    FAILED = "failed"
+    ABORTED = "aborted"
+
+
+class FailureDisposition(Enum):
+    TERMINAL = "terminal"
+    CALLER_DECISION = "caller_decision"
+
+
+class FailureCategory(Enum):
+    """What a backend knows about a failure beyond its exception, for callers that retry by themselves.
+
+    Disposition says who decides what happens next; the category says whether repeating can help.
+    """
+
+    UNCLASSIFIED = "unclassified"
+    """The backend adds nothing: the shared error classifier judges the exception."""
+    TRANSPORT = "transport"
+    """The connection ended before an answer: an idle timeout, a disconnect, an unexpected exit or an
+    unexpected cancel."""
+    REMOTE_ERROR = "remote_error"
+    """The remote agent reported a failure without saying whether a repeat can succeed."""
+    DEFINITIVE = "definitive"
+    """Configuration, launch (including an agent the connect retries could not reach), authentication,
+    refusal, truncation or empty output: a repeat ends the same way."""
+
+
+class AbortResult(Enum):
+    REQUESTED = "requested"
+    ALREADY_CONVERGED = "already_converged"
+
+
+class StaleContinuation(ValueError):
+    """The live single-use ticket no longer names this conversation state."""
+
+
+class OverlappingRun(RuntimeError):
+    """A conversation already has an unconverged pass."""
+
+
+class UnsupportedRequest(ValueError):
+    """The backend rejects this intent/content before any execution side effect."""
+
+
+@dataclass(frozen=True, slots=True)
+class ContinuationTicket:
+    conversation_id: str
+    failed_pass_id: str
+    state_generation: int
+    capability: ContinuationCapability
+
+
+@dataclass(frozen=True, slots=True)
+class RunRequest:
+    """A pass request, including a caller-preallocated logical identity.
+
+    Intent x capability admission (before hooks, history writes or transport):
+      continue_history: fresh requires messages and no ticket; continue accepts
+        empty input or messages, without a ticket; retry requires its live ticket.
+      fresh_session: fresh requires text messages and no ticket; continue is
+        unsupported; retry requires its live fresh_session ticket and text input.
+    A fresh empty text Message is different from an empty continuation sequence.
+    ACP accepts only user messages containing text, never silently drops images.
+    Kernel accepts a foreign-origin FRESH as a new logical invocation. The ACP
+    controller belongs to one fixed operation: foreign FRESH without a ticket
+    is UnsupportedRequest; foreign ticket-bearing input is StaleContinuation
+    after intent/content validation. Both backends order admission as closing
+    (ticket -> StaleContinuation, no ticket -> PreparedClosed), overlap,
+    intent/content table, then live-ticket identity/origin validation.
+
+    Exceptions: closed owner, overlapping run, stale ticket and unsupported
+    input are admission errors. After admission, provider/validation/pass-hook
+    failures return Failed (possibly without an exception for an ACP stop reason).
+    A latched caller abort returns Aborted; unrequested task cancellation still
+    propagates CancelledError after convergence. Shells retain their own terminal
+    projection and caller-operation cleanup beyond the pass boundary.
+    """
+
+    messages: Sequence[Message]
+    intent: RunIntent
+    origin: InvocationOrigin
+    continuation: ContinuationTicket | None = None
+
+
+def validate_request(request: RunRequest, capability: ContinuationCapability) -> None:
+    if not isinstance(request.origin, InvocationOrigin):
+        raise UnsupportedRequest("A live request requires an explicit origin")
+    if request.intent is RunIntent.FRESH:
+        if request.continuation is not None or not request.messages:
+            raise UnsupportedRequest("Fresh input requires messages and no continuation ticket")
+    elif request.intent is RunIntent.CONTINUE:
+        if capability is ContinuationCapability.FRESH_SESSION or request.continuation is not None:
+            raise UnsupportedRequest("This backend cannot continue the requested state")
+    elif request.intent is RunIntent.RETRY:
+        if request.continuation is None:
+            raise StaleContinuation("Retry requires a live continuation ticket")
+        if request.continuation.capability is not capability:
+            raise StaleContinuation("Continuation capability does not match this backend")
+    else:
+        raise UnsupportedRequest("Unknown run intent")
+    if capability is ContinuationCapability.FRESH_SESSION and (
+        not request.messages
+        or any(
+            message.role != "user" or any(content.type != "text" for content in message.contents)
+            for message in request.messages
+        )
+    ):
+        raise UnsupportedRequest("ACP accepts only user text input")
+
+
+@dataclass(frozen=True, slots=True)
+class UsageDelta:
+    """Observed spend; a missing report never becomes a complete zero."""
+
+    input_tokens: int = 0
+    output_tokens: int = 0
+    total_tokens: int = 0
+    complete: bool = False
+    unreported: int = 0
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Outcome:
+    handle: PassHandle
+    usage: UsageDelta
+    effects: PassEvidence
+    stop: StopCause
+    continuation: ContinuationTicket | None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Ok(Outcome):
+    """Raw successful output. Caller policy may fill structured_output lazily.
+
+    Backends always leave structured_output as None; they do not parse or
+    validate AgentResponse.value. Kernel backend_payload retains that response.
+    """
+
+    segments: tuple[Content, ...]
+    structured_output: object = None
+    backend_payload: object = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Failed(Outcome):
+    disposition: FailureDisposition
+    error: str
+    exception: Exception | None = None
+    category: FailureCategory = FailureCategory.UNCLASSIFIED
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Aborted(Outcome):
+    cause: AbortCause
+
+
+type InvocationOutcome = Ok | Failed | Aborted
+
+
+class AuditExport(Protocol):
+    """An explicit read-only audit port, with no implied mutable history."""
+
+    def export_audit(self) -> Mapping[str, object]: ...
+
+
+class InvocationConversation(Protocol):
+    """The backend-neutral pass interface; resource and caller owners are separate."""
+
+    async def run(self, request: RunRequest) -> InvocationOutcome: ...
+    async def abort(self, handle: PassHandle, cause: AbortCause) -> AbortResult: ...
+
+    @property
+    def active_handle(self) -> PassHandle | None: ...

chrys/orchestration/invoker/evidence.py

@@ -0,0 +1,94 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Scope-bound observations; wire snapshots are never invocation totals."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class Completeness(Enum):
+    EXACT = "exact"
+    LOWER_BOUND = "lower_bound"
+    UNKNOWN = "unknown"
+
+
+@dataclass(frozen=True, slots=True)
+class Count:
+    observed: int
+    completeness: Completeness
+
+    def __post_init__(self) -> None:
+        if self.observed < 0 or (self.completeness is Completeness.UNKNOWN and self.observed != 0):
+            raise ValueError("Counts must be nonnegative; UNKNOWN has no observed value")
+
+    def __add__(self, other: Count) -> Count:
+        observed = self.observed + other.observed
+        if self.completeness is other.completeness is Completeness.EXACT:
+            completeness = Completeness.EXACT
+        elif Completeness.LOWER_BOUND in (self.completeness, other.completeness) or observed:
+            completeness = Completeness.LOWER_BOUND
+        else:
+            completeness = Completeness.UNKNOWN
+        return Count(observed, completeness)
+
+
+UNKNOWN_COUNT = Count(0, Completeness.UNKNOWN)
+ZERO_COUNT = Count(0, Completeness.EXACT)
+
+
+def hosted_count(labels: tuple[str, ...] | None) -> Count:
+    """One hosted operation may have multiple labels (shell + shell result)."""
+    return UNKNOWN_COUNT if labels is None else Count(int(bool(labels)), Completeness.LOWER_BOUND)
+
+
+@dataclass(frozen=True, slots=True)
+class PassEvidence:
+    invocation_id: str
+    pass_id: str
+    local_dispatched: Count
+    local_answered: Count
+    hosted_observed: Count
+    external_stateful: bool | None
+
+
+@dataclass(frozen=True, slots=True)
+class WireSnapshot:
+    invocation_id: str
+    pass_id: str
+    wire_attempt: int
+    hosted_in_flight: Count
+
+
+@dataclass(frozen=True, slots=True)
+class InvocationEvidence:
+    """Caller-owned accumulation; each converged pass is accepted exactly once."""
+
+    invocation_id: str
+    passes: tuple[str, ...] = ()
+    local_dispatched: Count = ZERO_COUNT
+    local_answered: Count = ZERO_COUNT
+    hosted_observed: Count = ZERO_COUNT
+    external_stateful: bool | None = False
+
+    def add(self, evidence: PassEvidence) -> InvocationEvidence:
+        if not isinstance(evidence, PassEvidence):
+            raise TypeError("Only pass evidence may be accumulated")
+        if evidence.invocation_id != self.invocation_id or evidence.pass_id in self.passes:
+            raise ValueError("Foreign or already accumulated pass")
+        stateful = (
+            True
+            if self.external_stateful is True or evidence.external_stateful is True
+            else False
+            if self.external_stateful is False and evidence.external_stateful is False
+            else None
+        )
+        return InvocationEvidence(
+            self.invocation_id,
+            (*self.passes, evidence.pass_id),
+            self.local_dispatched + evidence.local_dispatched,
+            self.local_answered + evidence.local_answered,
+            self.hosted_observed + evidence.hosted_observed,
+            stateful,
+        )