iCode-TUI 0.29.1__py3-none-any.whl

chrys/orchestration/invoker/resources.py

@@ -0,0 +1,343 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Prepared, conversation and pass resources with a single close authority.
+
+Close tasks stay reachable through their owner until every release has run.
+Cancellation of a waiter cannot orphan the displaced build or cancel another
+close waiter. A release's own cancellation is remembered and re-raised after
+the remaining releases, matching the build transaction's former cleanup chain.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Awaitable, Callable, Coroutine
+from typing import Any
+
+from chrys.foundation.util.once_close import finish_close
+
+from .attempts import AttemptTaskHandle
+from .contracts import AbortCause, OperationBinding, PreparedClosed, Unbind
+
+logger = logging.getLogger(__name__)
+
+type Release = Callable[[], Awaitable[object]]
+
+
+async def rollback_resources(owner: ResourceScope) -> None:
+    """Complete rollback, preserving any new cancellation of its caller.
+
+    aclose/finish_close owns cancellation drainage. Only ordinary cleanup
+    failures are logged here so the caller can re-raise its acquisition error.
+    """
+    try:
+        await owner.aclose()
+    except Exception:
+        logger.exception("Error rolling back invocation resources")
+
+
+class ResourceScope:
+    """Reverse-acquisition release stack; concurrent closes share one task."""
+
+    def __init__(self) -> None:
+        self._releases: list[Release] = []
+        self._retained: list[object] = []
+        self._releasing: set[asyncio.Task[None]] = set()
+        self._close_task: asyncio.Task[None] | None = None
+
+    @property
+    def closing(self) -> bool:
+        return self._close_task is not None
+
+    def own(self, release: Release) -> None:
+        """Register the one release authority immediately after acquisition."""
+        if self.closing:
+            raise PreparedClosed("Resource owner is closing")
+        self._releases.append(release)
+
+    async def own_or_release(self, release: Release) -> None:
+        """Register *release* for a resource acquired across an ``await``.
+
+        This owner may start closing during that ``await``. It then refuses the
+        registration, so *release* runs here, drained even when this caller is
+        cancelled, and :class:`PreparedClosed` still propagates.
+        """
+        try:
+            self.own(release)
+        except PreparedClosed:
+
+            async def close_refused() -> None:
+                await release()
+
+            try:
+                await finish_close(asyncio.create_task(close_refused()))
+            except Exception:
+                logger.exception("Error releasing a resource its closing owner refused")
+            raise
+
+    def retain[T](self, resource: T) -> T:
+        """Keep private in-memory state reachable until this scope drains."""
+        if self.closing:
+            raise PreparedClosed("Resource owner is closing")
+        self._retained.append(resource)
+        return resource
+
+    async def release(self, release: Release) -> None:
+        """Release an operation-bound resource at its established shell boundary."""
+        self._releases.remove(release)
+
+        async def close_one() -> None:
+            await release()
+
+        task = asyncio.create_task(close_one())
+        self._releasing.add(task)
+        try:
+            await finish_close(task)
+        finally:
+            self._releasing.discard(task)
+
+    async def _close(self) -> None:
+        cancelled: asyncio.CancelledError | None = None
+        for task in tuple(self._releasing):
+            try:
+                await finish_close(task)
+            except asyncio.CancelledError as exc:
+                cancelled = exc
+            except Exception:
+                logger.exception("Error releasing invocation resource")
+        while self._releases:
+            release = self._releases.pop()
+            try:
+                await release()
+            except asyncio.CancelledError as exc:
+                cancelled = exc
+            except Exception:
+                logger.exception("Error releasing invocation resource")
+        self._retained.clear()
+        if cancelled is not None:
+            raise cancelled
+
+    async def aclose(self) -> None:
+        if self._close_task is None:
+            self._close_task = asyncio.create_task(self._close())
+        await finish_close(self._close_task)
+
+
+class PassResources(ResourceScope):
+    """A pass's mutable presentation and validation reset/cleanup lifetime.
+
+    This is only a resource scope, not an invocation handle or a backend run
+    contract. Validation instances belong to the conversation; their reset
+    hooks still execute inside the caller's existing pass try boundary.
+    """
+
+    def __init__(self, handle: AttemptTaskHandle, start_hooks: tuple[Callable[[], None], ...]) -> None:
+        super().__init__()
+        self.handle = handle
+        self._start_hooks = start_hooks
+
+    def begin(self) -> None:
+        for hook in self._start_hooks:
+            hook()
+
+    def request_close(self, cause: AbortCause) -> None:
+        self.handle.cancel()
+
+    @property
+    def drained(self) -> Awaitable[None]:
+        return self._drain()
+
+    async def _drain(self) -> None:
+        task = self.handle.task
+        if task is not None:
+            await asyncio.gather(task, return_exceptions=True)
+
+
+class Conversation(ResourceScope):
+    """Private runtime resources, plus the operation that currently uses them."""
+
+    def __init__(self, *, on_closed: Callable[[Conversation], None] | None = None) -> None:
+        super().__init__()
+        self._on_closed = on_closed
+        self._operation: OperationBinding | None = None
+        self._pass: OperationBinding | None = None
+
+    def bind_operation(self, binding: OperationBinding) -> Unbind:
+        if self.closing:
+            raise PreparedClosed("Conversation is closing")
+        if self._operation is not None:
+            raise RuntimeError("Conversation already has a bound operation")
+        self._operation = binding
+
+        def unbind() -> None:
+            if self._operation is binding:
+                self._operation = None
+
+        return unbind
+
+    def bind_pass(self, binding: OperationBinding) -> Unbind:
+        """Retain pass convergence when there is no caller operation binding."""
+        if self.closing:
+            raise PreparedClosed("Conversation is closing")
+        if self._pass is not None:
+            raise RuntimeError("Conversation already has a bound pass")
+        self._pass = binding
+
+        def unbind() -> None:
+            if self._pass is binding:
+                self._pass = None
+
+        return unbind
+
+    async def _close(self) -> None:
+        binding = self._operation or self._pass
+        cancelled: asyncio.CancelledError | None = None
+        try:
+            if binding is not None:
+                binding.request_close(AbortCause.OWNER_CLOSE)
+                await binding.drained
+        except asyncio.CancelledError as exc:
+            cancelled = exc
+        except Exception:
+            logger.exception("Error draining invocation operation")
+        finally:
+            try:
+                await super()._close()
+            finally:
+                if self._on_closed is not None:
+                    self._on_closed(self)
+        if cancelled is not None:
+            raise cancelled
+
+
+class PreparedAgent(ResourceScope):
+    """Shared resources, and the private conversations opened against them."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._conversations: list[Conversation] = []
+        self._opening: list[tuple[asyncio.Task[Any], asyncio.Event]] = []
+
+    async def open[T](self, factory: Callable[[Conversation], Awaitable[T]]) -> T:
+        """Acquire a private runtime, rolling back partial opens in reverse."""
+        if self.closing:
+            raise PreparedClosed("Prepared agent is closing")
+        conversation = Conversation(on_closed=self._forget_conversation)
+        task = asyncio.current_task()
+        if task is None:
+            raise RuntimeError("Opening a conversation requires an asyncio task.")
+        opening = (task, asyncio.Event())
+        self._opening.append(opening)
+        try:
+            value = await factory(conversation)
+            if self.closing:
+                raise PreparedClosed("Prepared agent closed during open")
+            self._conversations.append(conversation)
+            return value
+        except BaseException:
+            await rollback_resources(conversation)
+            raise
+        finally:
+            self._opening.remove(opening)
+            opening[1].set()
+
+    def _forget_conversation(self, conversation: Conversation) -> None:
+        if conversation in self._conversations:
+            self._conversations.remove(conversation)
+
+    async def _close(self) -> None:
+        opening = tuple(self._opening)
+        for task, _drained in opening:
+            task.cancel()
+        if opening:
+            # Await this acquire's rollback, not its caller task: the caller
+            # may itself join aclose() in its finally after open raises.
+            await asyncio.gather(*(drained.wait() for _task, drained in opening))
+        cancelled: asyncio.CancelledError | None = None
+        for conversation in reversed(tuple(self._conversations)):
+            try:
+                await conversation.aclose()
+            except asyncio.CancelledError as exc:
+                cancelled = exc
+        self._conversations.clear()
+        try:
+            await super()._close()
+        except asyncio.CancelledError as exc:
+            cancelled = exc
+        if cancelled is not None:
+            raise cancelled
+
+
+class OperationLifetime:
+    """Shell-owned completion barrier, including cleanup after the pass returns.
+
+    The common child shell owns this completion barrier from preparation through
+    its backend policy and terminal cleanup. Once cleanup
+    starts, owner-close latches but lets that cleanup finish in its original task.
+    """
+
+    def __init__(self) -> None:
+        self._task = asyncio.current_task()
+        self._done = asyncio.Event()
+        self._cleaning = False
+        self._requested = False
+        self._close_task: asyncio.Task[None] | None = None
+
+    @property
+    def drained(self) -> Awaitable[None]:
+        return self._drain()
+
+    async def _drain(self) -> None:
+        await self._done.wait()
+        if self._close_task is not None:
+            await finish_close(self._close_task)
+
+    def cancel_preparation(self) -> None:
+        self._requested = True
+        self._cancel_operation()
+
+    def _cancel_operation(self) -> None:
+        if not self._cleaning and self._task is not None and not self._task.done():
+            self._task.cancel()
+
+    def close_with(self, close: Callable[[], Coroutine[Any, Any, None]]) -> None:
+        """Run existing controller convergence, then wake a late pause callback."""
+        if self._requested:
+            return
+        self._requested = True
+
+        async def converge() -> None:
+            try:
+                await close()
+            finally:
+                self._cancel_operation()
+
+        self._close_task = asyncio.create_task(converge())
+
+    def begin_cleanup(self) -> None:
+        self._cleaning = True
+
+    def finish(self) -> None:
+        self._done.set()
+
+
+class TurnTaskBinding:
+    """A Turn shell's drain includes finalization and save on its owned task."""
+
+    def __init__(self, task: asyncio.Task[None], on_close: Callable[[AbortCause], None] | None) -> None:
+        self._task = task
+        self._on_close = on_close
+
+    def request_close(self, cause: AbortCause) -> None:
+        if self._on_close is not None:
+            self._on_close(cause)
+        if not self._task.done():
+            self._task.cancel()
+
+    @property
+    def drained(self) -> Awaitable[None]:
+        return self._drain()
+
+    async def _drain(self) -> None:
+        await asyncio.gather(self._task, return_exceptions=True)

chrys/orchestration/invoker/runtime.py

@@ -0,0 +1,299 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Per-conversation runtime factories and explicit main/child recipes.
+
+Prepared shares the client, stateless tools, MCP adapter and skills index.
+Context-management tools are generated by each private ContextManager, never
+included in SharedRuntime. Recipes retain each shell's context and chat order;
+callbacks here are bound to one conversation, not cached on the shared client.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, NotRequired, TypedDict
+
+from chrys.kernel import Agent, AgentSession
+from chrys.service.agent_middleware import ApprovalMiddleware, AskUserMiddleware
+from chrys.service.agent_middleware.reminders.archive_pointer import CATALOG_POINTER_RECORD_COUNT_STATE_KEY
+from chrys.service.agent_middleware.response_validation import ResponseValidationMiddleware
+from chrys.service.agent_middleware.system_reminder import ReminderTurns, SystemReminderMiddleware
+from chrys.service.context.compaction.last_words import LastWordsGenerator
+from chrys.service.context.compaction.last_words_state import LastWordsState
+from chrys.service.context.manager import ContextManager
+from chrys.service.vision import image_stub_middleware_for_model
+
+from .resources import Conversation
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable, Mapping
+    from pathlib import Path
+
+    from chrys.foundation.events.bus import EventBus
+    from chrys.foundation.models.session_env import SessionEnvironment
+    from chrys.foundation.retry import RetryAttemptInfo
+    from chrys.kernel.client import BaseChatClient
+    from chrys.kernel.middleware import ChatMiddleware
+    from chrys.service.agent_middleware.injection import InjectionMiddleware
+    from chrys.service.approval.judge import ApprovalJudge
+    from chrys.service.approval.policy import ApprovalMode, ApprovalPolicy
+    from chrys.service.approval.reuse_binding import ApprovalReuseBinding
+    from chrys.service.approval.turn_context import TurnContextHolder
+    from chrys.service.context.compaction import CompactionInfo, CompressInfo, 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.spill import SpillQuota
+    from chrys.service.hooks.manager import HookManager
+    from chrys.service.profiles.agents.schema import CompactionConfig
+    from chrys.service.profiles.models.schema import ModelProfile
+
+
+class ContextInputs(TypedDict):
+    """Explicit inputs to the conversation-owned ContextManager."""
+
+    profile: ModelProfile
+    on_usage: NotRequired[Callable[..., Any] | None]
+    on_compaction: NotRequired[Callable[[CompactionInfo], Awaitable[None]] | None]
+    on_pre_compact: NotRequired[Callable[[PreCompactInfo], Awaitable[None]] | None]
+    on_compress: NotRequired[Callable[[CompressInfo], Awaitable[None]] | None]
+    on_context_pressure: NotRequired[Callable[[str, DropRoundBreakerState, int], Awaitable[None] | None] | None]
+    spill_quota: NotRequired[SpillQuota | None]
+    spill_record_dir: NotRequired[Path | None]
+    debug_log_dir: NotRequired[Path | None]
+    compaction_config: NotRequired[CompactionConfig | None]
+    include_context_management: NotRequired[bool]
+    memory_text: NotRequired[str]
+    warn_threshold_pct: NotRequired[float]
+    session_id: NotRequired[str | None]
+    parent_session_id: NotRequired[str | None]
+    session_dir: NotRequired[Path | None]
+    skip_local_history_for_service_context: NotRequired[bool]
+    service_context_default_options: NotRequired[Mapping[str, Any] | None]
+
+
+class ReminderInputs(TypedDict):
+    """Explicit inputs to the conversation-owned SystemReminderMiddleware."""
+
+    runtime: NotRequired[SessionEnvironment | None]
+    max_context_tokens: NotRequired[int]
+    warn_threshold_pct: NotRequired[float]
+    sub_agent_names: NotRequired[list[str] | None]
+    shell_tool_enabled: NotRequired[bool]
+    tool_names: NotRequired[list[str] | None]
+    session_root: NotRequired[Path | None]
+    file_read_available: NotRequired[bool]
+    spill_quota: NotRequired[SpillQuota | None]
+    catalog_pointer_enabled: NotRequired[bool]
+    skill_catalog_provider: NotRequired[Callable[[], str | None] | None]
+    todo_state_provider: NotRequired[Callable[[], str | None] | None]
+    mcp_instructions_provider: NotRequired[Callable[[], str | None] | None]
+    file_change_provider: NotRequired[Callable[[], str | None] | None]
+
+
+class LastWordsInputs(TypedDict):
+    """Explicit inputs to the conversation-owned LastWordsGenerator."""
+
+    profile: ModelProfile
+    template: NotRequired[str]
+    max_output_tokens: NotRequired[int]
+    log_dir: NotRequired[Path | None]
+    session_id: NotRequired[str | None]
+    parent_session_id: NotRequired[str | None]
+    session_dir: NotRequired[Path | None]
+    max_transient_retries: NotRequired[int | None]
+    publish_retry: NotRequired[Callable[[RetryAttemptInfo], Awaitable[None]] | None]
+    publish_status: NotRequired[Callable[[CompactionStatus], Awaitable[None]] | None]
+    report_usage: NotRequired[Callable[[Mapping[str, Any]], None] | None]
+
+
+class ApprovalInputs(TypedDict):
+    """Explicit inputs to the conversation-owned ApprovalMiddleware."""
+
+    reuse: NotRequired[ApprovalReuseBinding | None]
+    approval_policy: ApprovalPolicy
+    event_bus: EventBus
+    session_id: NotRequired[str | None]
+    tool_kinds: NotRequired[dict[str, str] | None]
+    caller_name: NotRequired[str]
+    workspace_roots: NotRequired[list[str] | None]
+    approval_mode: NotRequired[ApprovalMode]
+    approval_judge: NotRequired[ApprovalJudge | None]
+    approval_log_dir: NotRequired[Path | None]
+    workspace_cwd: NotRequired[str | None]
+    dev_mode: NotRequired[bool]
+    hook_manager: NotRequired[HookManager | None]
+    profile_name: NotRequired[str]
+    session_archive_read_roots: NotRequired[list[Path] | None]
+    turn_context: NotRequired[TurnContextHolder | None]
+
+
+class AskUserInputs(TypedDict):
+    """Explicit inputs to the conversation-owned AskUserMiddleware."""
+
+    event_bus: EventBus
+    session_id: NotRequired[str | None]
+    caller_name: NotRequired[str]
+    timeout_seconds: NotRequired[int | None]
+
+
+@dataclass(frozen=True, slots=True)
+class SharedRuntime:
+    """Only Prepared-lifetime dependencies; no session-bound tool providers."""
+
+    client: BaseChatClient
+    tools: list[Any]
+    providers: list[Any]
+    name: str
+    instructions: str
+    vision: bool
+
+
+@dataclass(frozen=True, slots=True)
+class MainRecipe:
+    """Root context/usage before injection, image, reminder, validation."""
+
+    context: ContextInputs
+    reminder: ReminderInputs
+    last_words: LastWordsInputs
+    injection: Callable[[], InjectionMiddleware]
+    validation: Callable[[Conversation], ResponseValidationMiddleware]
+    persist_recovery: Callable[[], Awaitable[bool]] | None
+
+
+@dataclass(frozen=True, slots=True)
+class ChildRecipe:
+    """Private child context; image/reminder precede run usage/validation.
+
+    Registration's unused template keeps its historical usage middleware;
+    invocation wrappers never enter the shared client's context manager.
+    """
+
+    context: ContextInputs
+    reminder: ReminderInputs
+    last_words: LastWordsInputs
+    registration: bool
+
+
+@dataclass(slots=True)
+class KernelRuntime:
+    """The state owned by one conversation; the Agent borrows shared transport."""
+
+    owner: Conversation
+    agent: Agent
+    context: ContextManager
+    reminder: SystemReminderMiddleware
+    last_words: LastWordsState
+    injection: InjectionMiddleware | None = None
+    validation: ResponseValidationMiddleware | None = None
+
+    def create_session(self) -> AgentSession:
+        return self.agent.create_session()
+
+
+def create_context(inputs: ContextInputs) -> ContextManager:
+    return ContextManager(**inputs)
+
+
+def create_reminder(inputs: ReminderInputs) -> tuple[SystemReminderMiddleware, LastWordsState]:
+    """Build the reminder middleware and the LAST_WORDS state it renders, on one shared turn holder."""
+    turns = ReminderTurns()
+    last_words = LastWordsState(
+        turns,
+        spill_quota=inputs.get("spill_quota"),
+        session_root=inputs.get("session_root"),
+        file_read_available=inputs.get("file_read_available", False),
+        todo_provider=inputs.get("todo_state_provider"),
+    )
+    return SystemReminderMiddleware(**inputs, last_words=last_words), last_words
+
+
+def restore_phase4_state(
+    reminder: SystemReminderMiddleware,
+    last_words: LastWordsState,
+    state: Mapping[str, Any] | None,
+    *,
+    available_relative_paths: frozenset[str] | set[str] | None = None,
+) -> None:
+    """Restore persisted Phase 4 state: the LAST_WORDS slot and the catalog pointer's record count."""
+    if not reminder.renders_last_words(last_words):
+        raise ValueError("restore_phase4_state needs the LAST_WORDS state this reminder middleware renders")
+    state = state or {}
+    last_words.restore(state, available_relative_paths=available_relative_paths)
+    reminder.sources.archive_pointer.restore_record_count(state.get(CATALOG_POINTER_RECORD_COUNT_STATE_KEY))
+
+
+def create_runtime(
+    owner: Conversation,
+    shared: SharedRuntime,
+    recipe: MainRecipe | ChildRecipe,
+    *,
+    context: ContextManager | None = None,
+    injection: InjectionMiddleware | None = None,
+) -> KernelRuntime:
+    """Assemble fresh mutable runtime, preserving both established chat chains.
+
+    Main build prepares context before tool/skill progress, then completes it
+    here. Child opens construct context here, after the invocation skill refresh.
+    When context is supplied, recipe.context is not used to create a context.
+    """
+    ctx = create_context(recipe.context) if context is None else context
+    reminder, last_words = create_reminder(recipe.reminder)
+    ctx.compaction_strategy.bind_reminder(reminder, last_words)
+    if isinstance(recipe, MainRecipe) and recipe.persist_recovery is not None:
+        ctx.compaction_strategy.set_recovery_persistence_callback(recipe.persist_recovery)
+    generator = LastWordsGenerator(**recipe.last_words)
+    owner.own(generator.aclose)
+    ctx.compaction_strategy.set_last_words_generator(generator)
+    validation = recipe.validation(owner) if isinstance(recipe, MainRecipe) else None
+    if isinstance(recipe, MainRecipe):
+        injection = owner.retain(recipe.injection() if injection is None else injection)
+        injection.set_on_drained_reminders(reminder.queue_drained_injection_reminders)
+    chain: list[ChatMiddleware] = []
+    if isinstance(recipe, MainRecipe):
+        chain.extend(ctx.middleware)
+        if injection is None:
+            raise RuntimeError("The main agent recipe requires injection middleware.")
+        chain.append(injection)
+    elif recipe.registration:
+        chain.extend(ctx.middleware)
+    chain.append(image_stub_middleware_for_model(vision_enabled=shared.vision))
+    chain.append(reminder)
+    if isinstance(recipe, MainRecipe):
+        if validation is None:
+            raise RuntimeError("The main agent recipe requires response validation middleware.")
+        chain.append(validation)
+    agent = Agent(
+        client=shared.client,
+        name=shared.name,
+        instructions=shared.instructions,
+        tools=list(shared.tools),
+        context_providers=[*ctx.providers, *shared.providers],
+        middleware=chain,
+    )
+    return owner.retain(
+        KernelRuntime(
+            owner=owner,
+            agent=agent,
+            context=ctx,
+            reminder=reminder,
+            last_words=last_words,
+            injection=injection,
+            validation=validation,
+        )
+    )
+
+
+async def create_approval(owner: Conversation, inputs: ApprovalInputs) -> ApprovalMiddleware:
+    approval = ApprovalMiddleware(**inputs)
+    await owner.own_or_release(approval.close)
+    return approval
+
+
+def create_ask_user(owner: Conversation, inputs: AskUserInputs) -> AskUserMiddleware:
+    return owner.retain(AskUserMiddleware(**inputs))
+
+
+def create_validation(
+    owner: Conversation, *, publish_retry: Callable[[RetryAttemptInfo], Awaitable[None]] | None
+) -> ResponseValidationMiddleware:
+    return owner.retain(ResponseValidationMiddleware(publish_retry=publish_retry))