feat: partial turn preservation and cooperative stream cancellation

[cpsievert]

Summary

PR 2 in the streaming improvements series (after #276). Python port of ellmer's tidyverse/ellmer#951. Adds:

• Partial turn preservation: When a stream is interrupted (closed early, cancelled), the accumulated content so far is saved as a partial AssistantTurn with partial_reason set, so conversation state isn't lost
• StreamController: A cooperative cancellation mechanism for stream() and stream_async() — callers can request the stream stop cleanly via controller.cancel(), which triggers the partial turn preservation path
• Display improvements: Partial turns show [interrupted] in the Chat repr; partial turns are excluded from token accounting and cost calculations

Changes

• chatlas/_turn.py: Added partial_reason field to AssistantTurn and merge_content_text helper
• chatlas/_stream_controller.py: New StreamController class for cooperative cancellation
• chatlas/_chat.py: stream()/stream_async() accept optional controller parameter; _submit_turns/_submit_turns_async wrap streaming in try/finally to preserve partial turns on interruption
• chatlas/__init__.py: Export StreamController

Test plan

• make check-types passes (0 errors)
• VCR tests for partial turn preservation (sync + async)
• VCR tests for StreamController cancellation (sync + async)
• Snapshot test for [interrupted] display in Chat repr
• Existing tests still pass (495 passed, 11 skipped)

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (2)

chatlas/_chat.py:1271

• stream() wraps _chat_impl() but doesn’t explicitly close the underlying generator if the caller closes the wrapper early. Because the partial-turn preservation relies on generator finalization (finally in _submit_turns), it’s safer to ensure generator.close() is called in a finally block inside wrapper() so the partial turn (and provider response) are finalized deterministically (especially on non-refcounted Python implementations).

            controller=controller,
        )

        def wrapper() -> Generator[
            str | ContentThinking | ContentToolRequest | ContentToolResult, None, None

chatlas/_chat.py:1386

• Similar to the sync path: stream_async()’s wrapper doesn’t explicitly ensure the underlying async generator is closed when the wrapper is closed early. Adding a try/finally that awaits the inner generator’s aclose() (when available) would make partial-turn preservation and transport cleanup deterministic.

        controller = _as_controller(controller)

        async def wrapper() -> AsyncGenerator[
            str | ContentThinking | ContentToolRequest | ContentToolResult, None
        ]:
            with display:
                async for chunk in self._chat_impl_async(

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.