chore(types): reduce pyrefly errors 130 → 21 (another 84% drop on top of 38%)

Continues the clean-up on fix/pyrefly-zero-errors. Combined with the
prior commit, the total reduction this branch is 205 → 21 errors (90%).

**NoReturn annotations for error re-raisers** (−22 errors): Slack's
`_handle_slack_error` and Google Chat's `_handle_google_chat_error`
always raise but were typed `-> None`/`-> Any`, so every `try/except`
that propagated through them showed as "missing return". Annotated
both as `NoReturn` to let pyrefly skip the downstream paths.

**Framework-agnostic `request` duck-typing** (−14 not-async errors):
`hasattr(request, "text") and callable(request.text)` narrows `Any`
to `object`, making `await request.text()` fail type-checking. Swapped
to `getattr(request, "text", None)` (preserves `Any`) plus
`inspect.isawaitable` for the sync-vs-async branch — same runtime
behavior, but properly typed. Applied across all 7 adapters that
duck-type aiohttp / FastAPI / Flask requests. Bonus: also fixes the
latent runtime bug where a sync `request.text` (Flask) would have
raised `TypeError: object is not awaitable`.

**Handler sync/async union** (−3 not-async errors): handler types are
`Callable[..., Awaitable[None] | None]` but `_run_handlers`,
`_direct_message_handlers`, and pattern handlers all `await`
unconditionally. Switched to `inspect.isawaitable` guards — same
runtime fix, same pragmatism about the TS port's `Promise<void> |
void` convention.

**Protocol conformance**:
- `_ChatSingleton` now `Protocol` (was plain class), so `Chat`
  structurally satisfies it without an import cycle
- `ThreadImpl.channel` returns `Channel` (protocol) not `ChannelImpl`
  so `ThreadImpl` passes the `Thread` protocol
- `set_state` param renamed `new_state` → `state` to match protocol
- `_ChannelImplConfigForChat` removed (duplicate of
  `_ChannelImplConfigWithAdapter`)
- `ChatInstance` protocol now declares `handle_incoming_message`
  (Discord adapter was calling it but the protocol didn't advertise it)

**TypedDict unions duck-typed via `cast`**: many adapters `.get()`
against TypedDict unions where the key only exists on some variants.
Added narrow `cast(...)` calls where the code has already
runtime-verified the variant via a `type` check.

**Card-element helpers**: helpers typed `dict[str, Any]` but callers
passed `CardChild` (union of TypedDicts). Added `cast("dict[str, Any]",
child)` at the `_render_child` / `_convert_child_to_widgets` branches
— the variant is already narrowed via `child.get("type")`.

**Misc**:
- `WhatsAppRawMessage.message` tightened `dict[str, Any]` → `WhatsAppInboundMessage`
- `GitHubAdapter._parse_issue_comment` / `_parse_review_comment`
  param typed `GitHubRepository` instead of `dict[str, Any]`
- `_get_attachment_type` returns `Literal["audio","file","image","video"]`
- `is_encrypted_token_data` isn't a TypeGuard, so added an `assert`
  to collapse the `Optional` before the attribute access

Baseline regenerated: 213 → 21 entries (90% of original errors gone).
`pyrefly check --baseline=.pyrefly-baseline.json` shows 0 new errors.

Validation:
- `uv run pytest tests/ -q` → 3359 passed, 11 skipped
- `uv run ruff check src/ tests/ scripts/` → clean
- `uv run ruff format --check src/ tests/ scripts/` → clean
- `uv run pyrefly check --baseline=.pyrefly-baseline.json` → 0 new

Author: patrick-chinchill

.pyrefly-baseline.json

@@ -9,12 +9,13 @@
 from __future__ import annotations
 
 import hmac
+import inspect
 import json
 import os
 import re
 from contextvars import ContextVar
 from datetime import datetime, timezone
-from typing import Any
+from typing import Any, Literal, cast
 from urllib.parse import quote
 
 from chat_sdk.adapters.discord.cards import (
@@ -55,6 +56,7 @@
     LockScope,
     Message,
     MessageMetadata,
+    PostableRaw,
     RawMessage,
     ReactionEvent,
     SlashCommandEvent,
@@ -380,7 +382,11 @@ def _handle_application_command_interaction(
             self._logger.warn("Chat instance not initialized, ignoring interaction")
             return
 
-        data = interaction.get("data", {})
+        # `interaction["data"]` is a union of several TypedDicts (one per
+        # interaction type). Cast to a plain dict so we can access shared
+        # fields like `name` and `options` without pyrefly rejecting keys
+        # that only appear on one variant.
+        data = cast("dict[str, Any]", interaction.get("data", {}))
         command_name = data.get("name")
         if not command_name:
             self._logger.warn("No command name in application command interaction")
@@ -1160,7 +1166,7 @@ async def stream(
 
             accumulated += text
 
-            postable: AdapterPostableMessage = {"raw": accumulated}
+            postable: AdapterPostableMessage = PostableRaw(raw=accumulated)
 
             if message_id:
                 await self.edit_message(thread_id, message_id, postable)
@@ -1257,7 +1263,7 @@ def _parse_discord_message(self, raw: dict[str, Any], thread_id: str) -> Message
             ],
         )
 
-    def _get_attachment_type(self, mime_type: str | None) -> str:
+    def _get_attachment_type(self, mime_type: str | None) -> Literal["audio", "file", "image", "video"]:
         """Determine attachment type from MIME type."""
         if not mime_type:
             return "file"
@@ -1399,20 +1405,26 @@ async def _discord_fetch(
 
     async def _get_request_body(self, request: Any) -> str:
         """Extract the request body as a string."""
-        if hasattr(request, "body"):
-            body = request.body
+        # `hasattr` narrows `Any` to `object` and kills downstream type info,
+        # so we use `getattr(..., default)` which preserves `Any`. The
+        # `await` below is safe because `inspect.isawaitable` guards it.
+        body = getattr(request, "body", None)
+        if body is not None:
             if callable(body):
                 body = body()
             if hasattr(body, "read"):
-                raw = await body.read() if hasattr(body.read, "__await__") else body.read()
+                raw_read = body.read
+                raw = await raw_read() if inspect.iscoroutinefunction(raw_read) else raw_read()
                 return raw.decode("utf-8") if isinstance(raw, bytes) else raw
             return body.decode("utf-8") if isinstance(body, bytes) else str(body)
-        if hasattr(request, "text"):
-            if callable(request.text):
-                return await request.text()
-            return request.text
-        if hasattr(request, "data"):
-            data = request.data
+        text_attr = getattr(request, "text", None)
+        if text_attr is not None:
+            if callable(text_attr):
+                result = text_attr()
+                return str(await result if inspect.isawaitable(result) else result)
+            return text_attr
+        data = getattr(request, "data", None)
+        if data is not None:
             return data.decode("utf-8") if isinstance(data, bytes) else str(data)
         return ""
 

src/chat_sdk/adapters/discord/adapter.py

@@ -7,7 +7,7 @@
 
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, cast
 
 from chat_sdk.adapters.discord.types import DiscordActionRow, DiscordButton
 from chat_sdk.cards import (
@@ -113,12 +113,12 @@ def _process_child(
     elif child_type == "fields":
         _convert_fields_element(child, fields)  # type: ignore[arg-type]
     elif child_type == "link":
-        label = child.get("label", "")  # type: ignore[union-attr]
-        url = child.get("url", "")  # type: ignore[union-attr]
+        label = cast("str", child.get("label", ""))
+        url = cast("str", child.get("url", ""))
         text_parts.append(f"[{_convert_emoji(label)}]({url})")
     elif child_type == "table":
-        headers = child.get("headers", [])  # type: ignore[union-attr]
-        rows = child.get("rows", [])  # type: ignore[union-attr]
+        headers = cast("list[str]", child.get("headers", []))
+        rows = cast("list[list[str]]", child.get("rows", []))
         text_parts.append("\n".join(render_gfm_table(headers, rows)))
     else:
         text = card_child_to_fallback_text(child)
@@ -270,8 +270,8 @@ def _child_to_fallback_text(child: CardChild) -> str | None:
             if (t := _child_to_fallback_text(c))
         )
     if child_type == "table":
-        headers = child.get("headers", [])  # type: ignore[union-attr]
-        rows = child.get("rows", [])  # type: ignore[union-attr]
+        headers = cast("list[str]", child.get("headers", []))
+        rows = cast("list[list[str]]", child.get("rows", []))
         return f"```\n{table_element_to_ascii(headers, rows)}\n```"
     if child_type == "divider":
         return "---"

src/chat_sdk/adapters/discord/cards.py

@@ -11,6 +11,7 @@
 import asyncio
 import hashlib
 import hmac
+import inspect
 import json
 import os
 import re
@@ -26,6 +27,7 @@
     GitHubIssueComment,
     GitHubRawMessage,
     GitHubReactionContent,
+    GitHubRepository,
     GitHubReviewComment,
     GitHubThreadId,
     GitHubUser,
@@ -51,6 +53,7 @@
     LockScope,
     Message,
     MessageMetadata,
+    PostableMarkdown,
     RawMessage,
     StreamChunk,
     StreamOptions,
@@ -365,7 +368,7 @@ def _handle_review_comment(
     def _parse_issue_comment(
         self,
         comment: GitHubIssueComment,
-        repository: dict[str, Any],
+        repository: GitHubRepository,
         pr_number: int,
         thread_id: str,
         thread_type: Literal["pr", "issue"] = "pr",
@@ -409,7 +412,7 @@ def _parse_issue_comment(
     def _parse_review_comment(
         self,
         comment: GitHubReviewComment,
-        repository: dict[str, Any],
+        repository: GitHubRepository,
         pr_number: int,
         thread_id: str,
     ) -> Message:
@@ -528,7 +531,7 @@ async def stream(
                 text += chunk
             elif hasattr(chunk, "type") and chunk.type == "markdown_text":
                 text += chunk.text
-        return await self.post_message(thread_id, {"markdown": text})
+        return await self.post_message(thread_id, PostableMarkdown(markdown=text))
 
     @staticmethod
     def _build_raw_message(decoded: Any, comment: dict[str, Any]) -> dict[str, Any]:
@@ -889,8 +892,11 @@ async def fetch_channel_info(self, channel_id: str) -> ChannelInfo:
 
     def parse_message(self, raw: GitHubRawMessage) -> Message:
         """Parse a raw message into normalized format."""
+        # `raw` is a GitHubRawMessage dict with keys of varying value-types
+        # depending on the event variant; `.get()` unions to `object | str`.
+        # Narrow via casts where we've runtime-verified via `raw.get("type")`.
         if raw.get("type") == "issue_comment":
-            thread_type = raw.get("thread_type", "pr") or "pr"
+            thread_type = cast("Literal['issue', 'pr']", raw.get("thread_type", "pr") or "pr")
             thread_id = self.encode_thread_id(
                 GitHubThreadId(
                     owner=raw["repository"]["owner"]["login"],
@@ -900,10 +906,17 @@ def parse_message(self, raw: GitHubRawMessage) -> Message:
                 )
             )
             return self._parse_issue_comment(
-                raw["comment"], raw["repository"], raw["pr_number"], thread_id, thread_type
+                cast("GitHubIssueComment", raw["comment"]),
+                raw["repository"],
+                raw["pr_number"],
+                thread_id,
+                thread_type,
             )
         else:
-            root_comment_id = raw["comment"].get("in_reply_to_id") or raw["comment"]["id"]
+            root_comment_id = cast(
+                "int | None",
+                raw["comment"].get("in_reply_to_id") or raw["comment"]["id"],
+            )
             thread_id = self.encode_thread_id(
                 GitHubThreadId(
                     owner=raw["repository"]["owner"]["login"],
@@ -912,7 +925,12 @@ def parse_message(self, raw: GitHubRawMessage) -> Message:
                     review_comment_id=root_comment_id,
                 )
             )
-            return self._parse_review_comment(raw["comment"], raw["repository"], raw["pr_number"], thread_id)
+            return self._parse_review_comment(
+                cast("GitHubReviewComment", raw["comment"]),
+                raw["repository"],
+                raw["pr_number"],
+                thread_id,
+            )
 
     def render_formatted(self, content: FormattedContent) -> str:
         """Render formatted content to GitHub markdown."""
@@ -1069,10 +1087,14 @@ async def _get_installation_id(self, owner: str, repo: str) -> int | None:
     @staticmethod
     async def _get_request_body(request: Any) -> str:
         """Extract body text from a request object."""
-        if hasattr(request, "text") and callable(request.text):
-            return await request.text()
-        if hasattr(request, "body"):
-            body = request.body
+        # `hasattr` narrows `Any` → `object` (which is not awaitable), so
+        # `getattr(..., None)` keeps `Any` for the framework duck-type path.
+        text_attr = getattr(request, "text", None)
+        if text_attr is not None and callable(text_attr):
+            result = text_attr()
+            return str(await result if inspect.isawaitable(result) else result)
+        body = getattr(request, "body", None)
+        if body is not None:
             return body.decode("utf-8") if isinstance(body, bytes) else str(body)
         return ""
 

src/chat_sdk/adapters/github/adapter.py

@@ -6,7 +6,7 @@
 
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, cast
 
 from chat_sdk.cards import (
     CardChild,
@@ -92,42 +92,50 @@ def card_to_github_markdown(card: CardElement) -> str:
 
 
 def _render_child(child: CardChild) -> list[str]:
-    """Render a card child element to markdown lines."""
+    """Render a card child element to markdown lines.
+
+    The per-type helpers below accept `dict[str, Any]` because they access
+    dynamic keys (`content`, `label`, etc.) that are specific to one
+    variant of the `CardChild` union. The narrowing happens via the
+    `child_type` check, so casting to `dict[str, Any]` at the call sites
+    is safe and keeps the helpers simple.
+    """
     child_type = child.get("type", "")
 
     if child_type == "text":
-        return _render_text(child)
+        return _render_text(cast("dict[str, Any]", child))
 
     if child_type == "fields":
-        return _render_fields(child)
+        return _render_fields(cast("dict[str, Any]", child))
 
     if child_type == "actions":
-        return _render_actions(child)
+        return _render_actions(cast("dict[str, Any]", child))
 
     if child_type == "section":
         # Flatten section children
         result: list[str] = []
-        for section_child in child.get("children", []):
+        section_children = cast("list[CardChild]", child.get("children", []))
+        for section_child in section_children:
             result.extend(_render_child(section_child))
         return result
 
     if child_type == "image":
-        alt = child.get("alt", "")
-        url = child.get("url", "")
+        alt = cast("str", child.get("alt", ""))
+        url = cast("str", child.get("url", ""))
         if alt:
             return [f"![{_escape_markdown(alt)}]({url})"]
         return [f"![]({url})"]
 
     if child_type == "link":
-        label = child.get("label", "")
-        url = child.get("url", "")
+        label = cast("str", child.get("label", ""))
+        url = cast("str", child.get("url", ""))
         return [f"[{_escape_markdown(label)}]({url})"]
 
     if child_type == "divider":
         return ["---"]
 
     if child_type == "table":
-        return _render_table(child)
+        return _render_table(cast("dict[str, Any]", child))
 
     # Fallback
     text = card_child_to_fallback_text(child)
@@ -233,7 +241,7 @@ def _child_to_plain_text(child: CardChild) -> str | None:
         return None
 
     if child_type == "table":
-        return "\n".join(_render_table(child))
+        return "\n".join(_render_table(cast("dict[str, Any]", child)))
 
     if child_type == "section":
         return "\n".join(