docs(streaming): refresh native-vs-fallback wording (vercel/chat#463)

Ports the runtime-code portion of vercel/chat#463 (commit 0cc3d06) —
docstring cleanups around streaming. Upstream's #463 rewrote the
StreamingPlanOptions.updateIntervalMs comment from "fallback mode
(post + edit on adapters without native streaming)" to "Used by
post+edit streaming paths" because the interval is consulted regardless
of whether the adapter exposes its own ``stream`` method (Slack/Teams
adapters internally rate-limit edits using the same value). Same logic
applies to ThreadImpl._handle_stream's docstring and inline comment.

The other 0cc3d06 runtime fix — StreamEvent type 'step-finish' →
'finish-step' — was already correct on the Python side
(from_full_stream.py:79, thread.py:1273/1298), so nothing to do there.

Added load-bearing pins:
- TestStreamingPlanOptionsDocs::test_update_interval_ms_docstring_matches_upstream
- TestStreamingPlanOptionsDocs::test_thread_handle_stream_docstring_matches_upstream
Both fail if a future doc drift restores the stale wording.

Refs vercel/chat#463, tracking #98.

https://claude.ai/code/session_01FyMxQn2BEAzmwKS1GZczKj

Author: claude

CHANGELOG.md

@@ -5,6 +5,7 @@
 ### Documentation alignment
 
 - **DM routing precedence docstrings** (vercel/chat#491, commit `67c1794`). The Python runtime already routed direct messages to `on_direct_message` handlers before subscribed-message, mention, and pattern handlers (`Chat._handle_incoming_message`, `chat.py:2154`), but `on_direct_message` and `Thread.subscribe` lacked docstrings clarifying that contract. Refreshed both to match upstream's #491 docstring rewrite, plus a new `tests/integration/test_dm_flow.py::TestDMRoutingDocs` group and a `test_dm_handler_runs_before_pattern_handler` regression test that pin the documented precedence (DM > pattern) the previous suite did not explicitly cover. No runtime behavior change.
+- **Streaming docstring refresh** (vercel/chat#463, commit `0cc3d06`). Replaces stale "fallback mode (post + edit on adapters without native streaming)" wording on `StreamingPlanOptions.update_interval_ms` with "Used by post+edit streaming paths", matching upstream's #463 clarification (the interval is consulted regardless of whether the adapter exposes its own `stream` method — Slack/Teams may still rate-limit edits internally). Also reworks the `ThreadImpl._handle_stream` docstring + the in-function "Use native streaming if adapter supports it" comment so they no longer imply a binary native-vs-fallback split. The unrelated `step-finish` → `finish-step` upstream type fix was already correct in the Python port (`from_full_stream.py`, `thread.py`). No runtime behavior change.
 
 > Version bump from `0.4.29a2` to `0.4.29a3` will be cut by a coordinating PR once the parallel 4.29 ports land; this entry intentionally leaves `pyproject.toml` unchanged.
 

src/chat_sdk/plan.py

@@ -543,8 +543,7 @@ class StreamingPlanOptions:
         Useful for adding feedback buttons after a streamed response.
     update_interval_ms:
         Minimum interval between updates in ms (default: 500).
-        Used for fallback mode (post + edit on adapters without native
-        streaming).
+        Used by post + edit streaming paths.
     """
 
     group_tasks: Literal["plan", "timeline"] | None = None

src/chat_sdk/thread.py

@@ -648,7 +648,8 @@ async def _handle_stream(
     ) -> SentMessage:
         """Handle streaming from an AsyncIterable.
 
-        Uses adapter's native streaming if available, otherwise falls back to post+edit.
+        Uses the adapter's stream implementation if available, otherwise
+        falls back to post+edit.
 
         ``extra_options`` carries caller-supplied fields (e.g. from a
         :class:`StreamingPlan`: ``task_display_mode``, ``stop_blocks``,
@@ -682,7 +683,7 @@ async def _handle_stream(
             if extra_options.update_interval_ms is not None:
                 options.update_interval_ms = extra_options.update_interval_ms
 
-        # Use native streaming if adapter supports it
+        # Use adapter-provided streaming if available.
         if hasattr(self.adapter, "stream") and self.adapter.stream:  # type: ignore[union-attr]
             accumulated = ""
 

tests/test_plan.py

@@ -24,6 +24,7 @@
     Plan,
     PostableObjectContext,
     StartPlanOptions,
+    StreamingPlanOptions,
     UpdateTaskInput,
     is_postable_object,
     post_postable_object,
@@ -576,3 +577,37 @@ async def test_edit_failure_propagates_and_plan_continues(self) -> None:
         assert task is not None
         assert task.title == "Step 3"
         assert len(plan.tasks) == 3
+
+
+class TestStreamingPlanOptionsDocs:
+    """Pin the StreamingPlanOptions docstring to upstream's #463 refresh.
+
+    vercel/chat#463 (commit `0cc3d06`) dropped the stale "fallback mode (post
+    + edit on adapters without native streaming)" wording in favor of "Used
+    by post+edit streaming paths" — the same string is used regardless of
+    whether the adapter has a ``stream`` method (the adapter's stream method
+    may also internally rate-limit using this value). Without this lock,
+    Python could drift back to the old wording on the next sync.
+    """
+
+    def test_update_interval_ms_docstring_matches_upstream(self) -> None:
+        doc = StreamingPlanOptions.__doc__ or ""
+        # New (post-#463) wording
+        assert "post + edit streaming paths" in doc or "post+edit streaming paths" in doc
+        # Old wording must be gone
+        assert "fallback mode" not in doc
+        assert "without native streaming" not in doc
+
+    def test_thread_handle_stream_docstring_matches_upstream(self) -> None:
+        """ThreadImpl._handle_stream docstring uses the post-#463 wording.
+
+        Upstream rewrote the comment from "uses adapter's native streaming
+        if available" to "uses the adapter's stream implementation if
+        available" so the docs no longer imply a binary native/fallback
+        split (some adapters' ``stream`` method does its own post+edit).
+        """
+        doc = ThreadImpl._handle_stream.__doc__ or ""
+        # New (post-#463) wording
+        assert "stream implementation" in doc
+        # Old wording must be gone
+        assert "native streaming" not in doc