iCode-TUI 0.29.1__py3-none-any.whl

chrys/service/agent_middleware/control/approval_hooks.py

@@ -0,0 +1,62 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Observe human approval waits without participating in approval decisions."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+from chrys.service.hooks.events import HookEvent
+
+if TYPE_CHECKING:
+    from chrys.foundation.events.types import ApprovalResponse
+    from chrys.service.hooks.manager import HookManager
+
+
+async def await_approval_with_hooks(
+    *,
+    future: asyncio.Future[ApprovalResponse],
+    judge_task: asyncio.Task[None] | None,
+    manager: HookManager | None,
+    session_id: str | None,
+    profile_name: str,
+    workspace_cwd: str,
+    caller_name: str,
+    request_id: str,
+    tool_name: str,
+    tool_kind: str,
+    call_id: str,
+    args: dict[str, Any],
+    target_operation_id: str | None,
+) -> ApprovalResponse:
+    """Wait for the existing decision future, notifying only actual human waits."""
+    if manager is None or not (
+        manager.has_hooks_for(HookEvent.APPROVAL_REQUESTED) or manager.has_hooks_for(HookEvent.APPROVAL_RESOLVED)
+    ):
+        return await future
+
+    if judge_task is not None and not future.done():
+        # An AUTO verdict may fulfil the future. Only a still-pending decision
+        # after the judge finishes needs human attention.
+        await asyncio.wait((future, judge_task), return_when=asyncio.FIRST_COMPLETED)
+    if future.done():
+        return future.result()
+
+    payload = {
+        "session_id": session_id,
+        "profile": profile_name,
+        "cwd": workspace_cwd,
+        "caller_name": caller_name,
+        "request_id": request_id,
+        "tool": {"name": tool_name, "kind": tool_kind, "call_id": call_id, "args": args},
+    }
+    # These are observer events. Ignore every decision returned by the manager.
+    await manager.fire(HookEvent.APPROVAL_REQUESTED, payload, target_operation_id=target_operation_id)
+    result = await future
+    await manager.fire(
+        HookEvent.APPROVAL_RESOLVED,
+        {**payload, "approved": result.approved},
+        target_operation_id=target_operation_id,
+    )
+    return result

chrys/service/agent_middleware/control/ask_user.py

@@ -0,0 +1,207 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Ask-user middleware — intercepts ask_user tool calls to show a dialog."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+from uuid import uuid4
+
+from chrys.foundation.config.settings import DEFAULT_ASK_USER_TIMEOUT_SECONDS
+from chrys.foundation.events.types import AskUserResponse, AskUserTimedOut, QuestionToUser
+from chrys.foundation.models.ask_user import (
+    MAX_ASK_USER_DESCRIPTION_CHARS,
+    MAX_ASK_USER_HEADER_CHARS,
+    MAX_ASK_USER_LABEL_CHARS,
+    MAX_ASK_USER_OPTIONS,
+    MAX_ASK_USER_QUESTION_CHARS,
+    MAX_ASK_USER_QUESTIONS,
+    AskUserAnswer,
+    AskUserQuestion,
+    format_ask_user_result,
+    parse_ask_user_answers,
+    parse_ask_user_questions,
+)
+from chrys.foundation.tool_kinds import KIND_ASK_USER, get_tool_kind
+from chrys.foundation.trajectory.event_types import WaitCategory
+from chrys.kernel.middleware import FunctionMiddleware
+from chrys.service.agent_middleware._metadata_keys import _SHORT_ID_LEN
+from chrys.service.agent_middleware.events.hook_dispatch import get_call_id
+from chrys.service.approval.correlation import OneShotCorrelation
+from chrys.service.tools.result_metadata import tool_error
+from chrys.service.trajectory.tools import tool_operation_id
+from chrys.service.trajectory.waits import WaitOutcome, WaitTrace
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from chrys.foundation.events.bus import EventBus
+    from chrys.kernel.middleware import FunctionInvocationContext
+
+
+def _format_timeout(seconds: int) -> str:
+    """Render a timeout as whole minutes when divisible, else seconds."""
+    if seconds % 60 == 0:
+        minutes = seconds // 60
+        return f"{minutes} minute{'s' if minutes != 1 else ''}"
+    return f"{seconds} second{'s' if seconds != 1 else ''}"
+
+
+def _validate_questions(questions: tuple[AskUserQuestion, ...]) -> str | None:
+    if not questions:
+        return tool_error("ask_user_no_question", "no usable question was provided.", retryable=True)
+    if len(questions) > MAX_ASK_USER_QUESTIONS:
+        return tool_error(
+            "ask_user_too_many_questions",
+            f"ask_user accepts at most {MAX_ASK_USER_QUESTIONS} questions.",
+            retryable=True,
+            details={"max_questions": MAX_ASK_USER_QUESTIONS},
+        )
+    for question_index, question in enumerate(questions):
+        if len(question.options) > MAX_ASK_USER_OPTIONS:
+            return tool_error(
+                "ask_user_too_many_options",
+                f"question {question_index + 1} has more than {MAX_ASK_USER_OPTIONS} options.",
+                retryable=True,
+                details={"question_index": question_index, "max_options": MAX_ASK_USER_OPTIONS},
+            )
+        field_lengths = (
+            ("question", question.question, MAX_ASK_USER_QUESTION_CHARS),
+            ("header", question.header, MAX_ASK_USER_HEADER_CHARS),
+        )
+        for field_name, value, cap in field_lengths:
+            if len(value) > cap:
+                return tool_error(
+                    "ask_user_field_too_long",
+                    f"question {question_index + 1} field {field_name!r} exceeds {cap} characters.",
+                    retryable=True,
+                    details={"question_index": question_index, "field": field_name, "max_chars": cap},
+                )
+        seen_labels: set[str] = set()
+        for option_index, option in enumerate(question.options):
+            option_fields = (
+                ("label", option.label, MAX_ASK_USER_LABEL_CHARS),
+                ("description", option.description, MAX_ASK_USER_DESCRIPTION_CHARS),
+            )
+            for field_name, value, cap in option_fields:
+                if len(value) > cap:
+                    return tool_error(
+                        "ask_user_field_too_long",
+                        f"question {question_index + 1} option {option_index + 1} field {field_name!r} "
+                        f"exceeds {cap} characters.",
+                        retryable=True,
+                        details={
+                            "question_index": question_index,
+                            "option_index": option_index,
+                            "field": field_name,
+                            "max_chars": cap,
+                        },
+                    )
+            if option.label in seen_labels:
+                return tool_error(
+                    "ask_user_duplicate_options",
+                    f"question {question_index + 1} contains duplicate option labels.",
+                    retryable=True,
+                    details={"question_index": question_index, "label": option.label},
+                )
+            seen_labels.add(option.label)
+    return None
+
+
+def _answers_from_response(response: AskUserResponse, *, question_count: int) -> tuple[AskUserAnswer, ...]:
+    return parse_ask_user_answers(response.answers or (), question_count=question_count)
+
+
+class AskUserMiddleware(FunctionMiddleware):
+    """Intercepts ``ask_user`` tool calls to show a dialog and wait for a response.
+
+    Follows the same pattern as ``ApprovalMiddleware``: publishes a
+    ``QuestionToUser`` event, awaits the ``AskUserResponse``, and writes
+    the user's answer into ``context.result`` — the underlying tool function
+    is never invoked.
+
+    ``timeout_seconds`` bounds how long to wait for the reply.  ``None`` waits
+    indefinitely (no ``AskUserTimedOut``) — used by frontends that own the
+    interaction lifetime themselves (e.g. ACP clients).
+    """
+
+    def __init__(
+        self,
+        event_bus: EventBus,
+        session_id: str | None = None,
+        caller_name: str = "",
+        *,
+        timeout_seconds: int | None = DEFAULT_ASK_USER_TIMEOUT_SECONDS,
+    ) -> None:
+        self._bus = event_bus
+        self._session_id = session_id
+        self._caller_name = caller_name
+        self._timeout_seconds = timeout_seconds
+
+    async def process(
+        self,
+        context: FunctionInvocationContext,
+        call_next: Callable[[], Awaitable[None]],
+    ) -> None:
+        if get_tool_kind(context.function) != KIND_ASK_USER:
+            await call_next()
+            return
+
+        args = context.arguments if isinstance(context.arguments, dict) else {}
+        questions = parse_ask_user_questions(args)
+        if error := _validate_questions(questions):
+            context.result = error
+            return
+
+        request_id = uuid4().hex[:_SHORT_ID_LEN]
+
+        # Subscribe before publishing. Publishing awaits frontend handlers and
+        # can be cancelled before the response wait starts, so the subscription
+        # is owned across that whole interval.
+        async with OneShotCorrelation(self._bus, AskUserResponse, request_id=request_id) as correlation:
+            future = correlation.future
+            await self._bus.publish(
+                QuestionToUser(
+                    request_id=request_id,
+                    questions=questions,
+                    session_id=self._session_id,
+                    call_id=get_call_id(context),
+                    caller_name=self._caller_name,
+                )
+            )
+
+            timeout = self._timeout_seconds
+            wait = WaitTrace.open(WaitCategory.USER_INPUT, target_operation_id=tool_operation_id(context.metadata))
+            try:
+                # Inside the block that closes the wait and drops the subscription:
+                # the start marker awaits its write ack, and an interrupt landing
+                # there is exactly the case the cancellation branch below exists for.
+                if wait is not None:
+                    await wait.started()
+                response = await (future if timeout is None else asyncio.wait_for(future, timeout=timeout))
+                if response.cancelled:
+                    context.result = tool_error(
+                        "ask_user_no_response",
+                        "user did not provide a response.",
+                        retryable=True,
+                    )
+                else:
+                    answers = _answers_from_response(response, question_count=len(questions))
+                    context.result = format_ask_user_result(questions, answers)
+                if wait is not None:
+                    await wait.finished()
+            except TimeoutError:
+                if wait is not None:
+                    await wait.finished(outcome=WaitOutcome.TIMED_OUT)
+                context.result = tool_error(
+                    "ask_user_timeout",
+                    f"user did not respond within {_format_timeout(timeout or 0)}.",
+                    retryable=True,
+                    details={"timeout_seconds": timeout or 0},
+                )
+                await self._bus.publish(AskUserTimedOut(request_id=request_id, session_id=self._session_id))
+            except asyncio.CancelledError:
+                if wait is not None:
+                    wait.finished_soon(outcome=WaitOutcome.CANCELLED)
+                raise

chrys/service/agent_middleware/control/interrupt.py

@@ -0,0 +1,50 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Interrupt middleware — stops execution at the next tool call boundary."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from chrys.kernel.middleware import FunctionMiddleware
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from chrys.kernel.middleware import FunctionInvocationContext
+
+
+class InterruptMiddleware(FunctionMiddleware):
+    """Checks for an interrupt flag between tool calls.
+
+    When the interrupt flag is set, raises MiddlewareTermination to stop
+    execution at the next tool call boundary.
+    """
+
+    def __init__(self) -> None:
+        self._interrupted = False
+
+    @property
+    def is_interrupted(self) -> bool:
+        """True if an interrupt has been signalled and not yet reset."""
+        return self._interrupted
+
+    def set_interrupted(self) -> None:
+        """Signal that execution should stop at the next tool call."""
+        self._interrupted = True
+
+    def reset(self) -> None:
+        """Clear the interrupt flag."""
+        self._interrupted = False
+
+    async def process(
+        self,
+        context: FunctionInvocationContext,
+        call_next: Callable[[], Awaitable[None]],
+    ) -> None:
+        if self._interrupted:
+            from chrys.kernel.middleware import MiddlewareTermination
+
+            raise MiddlewareTermination("Execution interrupted by user")
+
+        await call_next()

chrys/service/agent_middleware/control/sleep.py

@@ -0,0 +1,118 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Sleep middleware — intercepts sleep tool calls so the TUI can skip them."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import TYPE_CHECKING
+
+from chrys.foundation.events.types import SleepSkip, UserInterrupt
+from chrys.foundation.tool_kinds import KIND_SLEEP, get_tool_kind
+from chrys.kernel.middleware import FunctionMiddleware
+from chrys.service.agent_middleware._metadata_keys import _SLEEP_INTERRUPTED_KEY, _SLEEP_SKIPPED_KEY
+from chrys.service.agent_middleware.events.hook_dispatch import get_call_id
+from chrys.service.tools.builtins.sleep import format_sleep_seconds, parse_sleep_seconds
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from chrys.foundation.events.bus import EventBus
+    from chrys.kernel.middleware import FunctionInvocationContext
+
+
+class SleepMiddleware(FunctionMiddleware):
+    """Intercept ``sleep`` tool calls and race the timer against skip/interrupt events."""
+
+    def __init__(self, event_bus: EventBus, session_id: str | None = None) -> None:
+        self._bus = event_bus
+        self._session_id = session_id
+        self._active: dict[str, asyncio.Future[str]] = {}
+
+    @property
+    def active_call_ids(self) -> tuple[str, ...]:
+        """Call ids for sleep invocations that can currently be interrupted."""
+        return tuple(self._active)
+
+    def interrupt_active(self) -> tuple[str, ...]:
+        """Resolve all active sleeps as interrupted and return their call ids."""
+        interrupted: list[str] = []
+        for call_id, future in list(self._active.items()):
+            if not future.done():
+                future.set_result("interrupted")
+                interrupted.append(call_id)
+        return tuple(interrupted)
+
+    async def process(
+        self,
+        context: FunctionInvocationContext,
+        call_next: Callable[[], Awaitable[None]],
+    ) -> None:
+        if get_tool_kind(context.function) != KIND_SLEEP:
+            await call_next()
+            return
+
+        args = context.arguments if isinstance(context.arguments, dict) else {}
+        seconds = parse_sleep_seconds(args.get("seconds"))
+        if isinstance(seconds, str):
+            context.result = seconds
+            return
+
+        call_id = get_call_id(context)
+        start = time.monotonic()
+        loop = asyncio.get_running_loop()
+        resolved: asyncio.Future[str] = loop.create_future()
+        if call_id:
+            self._active[call_id] = resolved
+
+        async def _skip_handler(event: SleepSkip) -> None:
+            if call_id and event.call_id == call_id and not resolved.done():
+                resolved.set_result("skipped")
+
+        async def _interrupt_handler(event: UserInterrupt) -> None:
+            if event.session_id and self._session_id and event.session_id != self._session_id:
+                return
+            # In engine-managed runs, Executor.interrupt() usually resolves active
+            # sleeps first so they can publish ToolCallResult before task cancellation.
+            # Keep this bus handler as the standalone middleware contract: callers
+            # that publish UserInterrupt without an Executor still interrupt sleep.
+            if not resolved.done():
+                resolved.set_result("interrupted")
+
+        await self._bus.subscribe(SleepSkip, _skip_handler)
+        await self._bus.subscribe(UserInterrupt, _interrupt_handler)
+        try:
+            while True:
+                elapsed = time.monotonic() - start
+                remaining = seconds - elapsed
+                if remaining <= 0:
+                    context.result = f"Slept for {format_sleep_seconds(seconds)}."
+                    return
+                try:
+                    # Wake in short ticks so cancellation and timer drift stay bounded.
+                    # ``shield`` keeps the shared event Future reusable after wait_for timeouts.
+                    resolution = await asyncio.wait_for(asyncio.shield(resolved), timeout=min(1.0, remaining))
+                except TimeoutError:
+                    continue
+                elapsed_seconds = min(seconds, int(time.monotonic() - start))
+                if resolution == "interrupted":
+                    if isinstance(context.metadata, dict):
+                        context.metadata[_SLEEP_INTERRUPTED_KEY] = True
+                    context.result = (
+                        f"Sleep interrupted after {format_sleep_seconds(elapsed_seconds)} "
+                        f"(requested {format_sleep_seconds(seconds)})."
+                    )
+                else:
+                    if isinstance(context.metadata, dict):
+                        context.metadata[_SLEEP_SKIPPED_KEY] = True
+                    context.result = (
+                        f"Sleep skipped by user after {format_sleep_seconds(elapsed_seconds)} "
+                        f"(requested {format_sleep_seconds(seconds)})."
+                    )
+                return
+        finally:
+            if call_id and self._active.get(call_id) is resolved:
+                del self._active[call_id]
+            await self._bus.unsubscribe(SleepSkip, _skip_handler)
+            await self._bus.unsubscribe(UserInterrupt, _interrupt_handler)

chrys/service/agent_middleware/control/todo.py

@@ -0,0 +1,117 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Todo middleware — intercepts todo_write tool calls to update the session todo list."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+from chrys.foundation.events.types import TodoListUpdated
+from chrys.foundation.models.todos import MAX_TODO_ITEMS, MAX_TODO_TEXT_LENGTH, TodoItem, TodoStatus
+from chrys.foundation.tool_kinds import KIND_TODO, get_tool_kind
+from chrys.kernel.middleware import FunctionMiddleware
+from chrys.service.tools.result_metadata import tool_error
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from chrys.foundation.events.bus import EventBus
+    from chrys.kernel.middleware import FunctionInvocationContext
+    from chrys.service.todos.tracker import TodoTracker
+
+
+class TodoMiddleware(FunctionMiddleware):
+    """Intercepts ``todo_write`` calls: validate → apply to the tracker → publish.
+
+    Follows the ``AskUserMiddleware`` intercept pattern — the underlying tool
+    function is never invoked; ``context.result`` carries the outcome.
+
+    Validation here covers only what the JSON schema cannot express (item
+    count, per-field length caps, non-empty content). Type/shape/status errors
+    fail kernel pre-pipeline argument validation and never reach this
+    middleware.
+    """
+
+    def __init__(self, event_bus: EventBus, tracker: TodoTracker, session_id: str | None = None) -> None:
+        self._bus = event_bus
+        self._tracker = tracker
+        self._session_id = session_id
+
+    async def process(
+        self,
+        context: FunctionInvocationContext,
+        call_next: Callable[[], Awaitable[None]],
+    ) -> None:
+        if get_tool_kind(context.function) != KIND_TODO:
+            await call_next()
+            return
+
+        # Same-batch duplicates: with whole-list replacement, the surviving
+        # list of two gathered todo_write calls would be scheduling-defined.
+        # Reject ALL of them — zero winners is deterministic; the model
+        # resends a single call with the complete list.
+        if context.same_tool_calls_in_batch > 1:
+            context.result = tool_error(
+                "todo_batch_conflict",
+                "multiple todo_write calls in one response; send a single call with the complete list.",
+            )
+            return
+
+        args = context.arguments if isinstance(context.arguments, dict) else {}
+        raw_todos = args.get("todos")
+        if not isinstance(raw_todos, list):
+            context.result = tool_error("todo_invalid", "todo_write requires a 'todos' list.")
+            return
+        if len(raw_todos) > MAX_TODO_ITEMS:
+            context.result = tool_error(
+                "todo_invalid",
+                f"too many todo items ({len(raw_todos)}); the list is capped at {MAX_TODO_ITEMS}.",
+            )
+            return
+
+        items: list[TodoItem] = []
+        for index, entry in enumerate(raw_todos):
+            data = entry if isinstance(entry, dict) else {}
+            content = data.get("content", "")
+            active_form = data.get("active_form", "")
+            if not isinstance(content, str) or not content.strip():
+                context.result = tool_error("todo_invalid", f"todo item {index + 1} has empty content.")
+                return
+            if len(content) > MAX_TODO_TEXT_LENGTH:
+                context.result = tool_error(
+                    "todo_invalid",
+                    f"todo item {index + 1} content exceeds {MAX_TODO_TEXT_LENGTH} characters.",
+                )
+                return
+            if isinstance(active_form, str) and len(active_form) > MAX_TODO_TEXT_LENGTH:
+                context.result = tool_error(
+                    "todo_invalid",
+                    f"todo item {index + 1} active_form exceeds {MAX_TODO_TEXT_LENGTH} characters.",
+                )
+                return
+            items.append(
+                TodoItem(
+                    content=content,
+                    # Kernel schema validation admits only ``TodoStatus``
+                    # literals before middleware dispatch.
+                    status=cast("TodoStatus", data.get("status", "pending")),
+                    active_form=active_form if isinstance(active_form, str) else "",
+                )
+            )
+
+        applied = await self._tracker.replace(tuple(items))
+        # Publish AFTER the tracker lock is released: EventBus.publish awaits
+        # subscriber callbacks inline, so a lock-held publish would span
+        # arbitrary UI/ACP handlers. The event carries the exact applied
+        # snapshot, and reject-all above means at most one apply per batch, so
+        # published state cannot invert. session_id is REQUIRED: host streams
+        # drop sessionless events in _event_belongs_to_session.
+        await self._bus.publish(TodoListUpdated(items=list(applied), session_id=self._session_id))
+
+        completed = sum(1 for item in applied if item.status == "completed")
+        in_progress = sum(1 for item in applied if item.status == "in_progress")
+        pending = len(applied) - completed - in_progress
+        context.result = (
+            f"Todo list updated: {len(applied)} items "
+            f"({completed} completed, {in_progress} in progress, {pending} pending)."
+        )

chrys/service/agent_middleware/events/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Event-publishing middleware."""