Method send_and_wait

python/copilot/session.py:1559–1682

Send a message to this session and wait until the session becomes idle. This is a convenience method that combines :meth:`send` with waiting for the session.idle event. Use this when you want to block until the assistant has finished processing the message.

(
        self,
        prompt: str,
        *,
        attachments: list[Attachment] | None = None,
        mode: Literal["enqueue", "immediate"] | None = None,
        agent_mode: Literal["interactive", "plan", "autopilot", "shell"] | None = None,
        request_headers: dict[str, str] | None = None,
        display_prompt: str | None = None,
        timeout: float = 60.0,
    )

        return message_id

    async def send_and_wait(
        self,
        prompt: str,
        *,
        attachments: list[Attachment] | None = None,
        mode: Literal["enqueue", "immediate"] | None = None,
        agent_mode: Literal["interactive", "plan", "autopilot", "shell"] | None = None,
        request_headers: dict[str, str] | None = None,
        display_prompt: str | None = None,
        timeout: float = 60.0,
    ) -> SessionEvent | None:
        """
        Send a message to this session and wait until the session becomes idle.

        This is a convenience method that combines :meth:`send` with waiting for
        the session.idle event. Use this when you want to block until the assistant
        has finished processing the message.

        Events are still delivered to handlers registered via :meth:`on` while waiting.

        Args:
            prompt: The message text to send.
            attachments: Optional file, directory, or selection attachments.
            mode: Message delivery mode (``"enqueue"`` or ``"immediate"``).
            agent_mode: The UI mode the agent was in when this message was sent
                (for example ``"plan"`` or ``"autopilot"``). Defaults to the
                session's current mode when unset.
            request_headers: Optional per-turn HTTP headers for outbound model requests.
            display_prompt: If provided, this is shown in the timeline instead of
                ``prompt``.
            timeout: Timeout in seconds (default: 60). Controls how long to wait;
                does not abort in-flight agent work.

        Returns:
            The final assistant message event, or None if none was received.

        Raises:
            TimeoutError: If the timeout is reached before session becomes idle.
            Exception: If the session has been disconnected or the connection fails.

        Example:
            >>> from copilot.session_events import AssistantMessageData
            >>> response = await session.send_and_wait("What is 2+2?")
            >>> if response:
            ...     match response.data:
            ...         case AssistantMessageData() as data:
            ...             print(data.content)
        """
        total_start = time.perf_counter()
        idle_event = asyncio.Event()
        error_event: Exception | None = None
        last_assistant_message: SessionEvent | None = None
        first_assistant_message_logged = False

        def handler(event: SessionEventTypeAlias) -> None:
            nonlocal first_assistant_message_logged, last_assistant_message, error_event
            match event.data:
                case AssistantMessageData():