chore(types): reduce pyrefly errors from 213 → 130 (38% drop)

Tackles the largest clusters of real type issues without resorting to
`# type: ignore`:

**Protocol conformance (lock_scope)** — all 8 adapters typed `lock_scope`
as `str | None` instead of `LockScope | None` (`Literal['channel',
'thread'] | None`), so every adapter failed the `Adapter` protocol,
cascading through every `adapter=self` call site (ActionEvent,
ReactionEvent, etc.). Fixed at the source + propagated to internal
`_lock_scope` fields on stateful adapters.

**Protocol conformance (parameter names)** — protocols compare parameter
names, not just types. Several adapters named params `_thread_id` /
`_status` / `_emoji` to signal "unused", which broke structural typing
against `Adapter`. Renamed to match the protocol.

**Optional dep submodule imports** — `replace-imports-with-any` only
matched top-level (`slack_sdk`, `nacl`, `redis`), so submodule imports
(`slack_sdk.web.async_client`, `nacl.signing`, `redis.asyncio`) still
flagged. Added `.*` wildcards for each optional dep.

**TypedDict keys that are Python keywords** — `WhatsAppInboundMessage`
had `from_` but the runtime JSON key is `"from"`, so every
`message["from"]` access flagged bad-typed-dict-key. Converted to
functional-form TypedDict so the Python source can spell `"from"` as
a string key.

**TypedDict union duck-typing** — GitHub adapter's init detects auth
mode via `config.get("token")` / `.get("app_id")`, but the public
config type is a union of 4 auth-specific TypedDicts where no single
variant has all keys. Added an internal superset TypedDict
(`_GitHubAdapterConfigInternal`) cast at the init boundary so the
duck-typing stays type-safe without fragmenting the public API.

**Event types accepting None** — `ReactionEvent.thread` and
`SlashCommandEvent.channel` were typed as required, but adapters
legitimately don't always have a Thread/Channel at dispatch time (e.g.
Slack reactions on channel-root messages, Discord DM slash commands).
Relaxed to `Thread | None` / `Channel | None` with a docstring note
for consumers.

Baseline regenerated (`uv run pyrefly check --baseline ...
--update-baseline`) — reduced from 213 → 130 entries, all remaining
entries are now on the local repo paths (previous baseline had
`/home/user/...` artifacts from the cloud agent env that never
matched locally).

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

Author: patrick-chinchill

.pyrefly-baseline.json

@@ -99,19 +99,26 @@ python-platform = "linux"
 # Optional adapter deps that aren't in the default install. Treating them as
 # Any keeps pyrefly from flagging missing-import every time we lazy-load one.
 replace-imports-with-any = [
-    # Slack
+    # Slack — covers top-level + submodule imports like slack_sdk.web.async_client
     "slack_sdk",
-    # Discord
+    "slack_sdk.*",
+    # Discord — signed-request verification uses pynacl's nacl.signing
     "nacl",
-    # Google Chat
+    "nacl.*",
+    # Google Chat — auth uses google.auth.* subpackages
     "google",
+    "google.*",
     # State backends
     "redis",
+    "redis.*",
     "asyncpg",
+    "asyncpg.*",
     # HTTP clients used in lazy paths
     "httpx",
+    "httpx.*",
     # GitHub App auth
     "jwt",
+    "jwt.*",
 ]
 
 [tool.pyrefly.errors]

pyproject.toml

@@ -52,6 +52,7 @@
     FetchResult,
     FileUpload,
     FormattedContent,
+    LockScope,
     Message,
     MessageMetadata,
     RawMessage,
@@ -160,7 +161,7 @@ def bot_user_id(self) -> str | None:
         return self._bot_user_id
 
     @property
-    def lock_scope(self) -> str | None:
+    def lock_scope(self) -> LockScope | None:
         return None
 
     @property
@@ -953,7 +954,7 @@ async def remove_reaction(
             "DELETE",
         )
 
-    async def start_typing(self, thread_id: str, _status: str | None = None) -> None:
+    async def start_typing(self, thread_id: str, status: str | None = None) -> None:
         """Start typing indicator in a Discord channel or thread."""
         decoded = self.decode_thread_id(thread_id)
         target_channel_id = decoded.thread_id or decoded.channel_id

src/chat_sdk/adapters/discord/adapter.py

@@ -17,7 +17,7 @@
 import time
 from collections.abc import AsyncIterable
 from datetime import datetime, timezone
-from typing import Any, Literal
+from typing import Any, Literal, cast
 
 from chat_sdk.adapters.github.cards import card_to_github_markdown
 from chat_sdk.adapters.github.format_converter import GitHubFormatConverter
@@ -31,6 +31,7 @@
     GitHubUser,
     IssueCommentWebhookPayload,
     PullRequestReviewCommentWebhookPayload,
+    _GitHubAdapterConfigInternal,
 )
 from chat_sdk.emoji import convert_emoji_placeholders
 from chat_sdk.logger import ConsoleLogger, Logger
@@ -47,6 +48,7 @@
     FormattedContent,
     ListThreadsOptions,
     ListThreadsResult,
+    LockScope,
     Message,
     MessageMetadata,
     RawMessage,
@@ -89,7 +91,10 @@ class GitHubAdapter:
     """
 
     def __init__(self, config: GitHubAdapterConfig | None = None) -> None:
-        config = config or {}
+        # The public API surface is the auth-mode-specific TypedDict union
+        # above; internally we duck-type with `.get()` so narrow to the
+        # superset TypedDict that admits every possible key.
+        config = cast(_GitHubAdapterConfigInternal, config or {})
         self._name = "github"
 
         webhook_secret = config.get("webhook_secret") or os.environ.get("GITHUB_WEBHOOK_SECRET")
@@ -177,7 +182,7 @@ def bot_user_id(self) -> str | None:
         return str(self._bot_user_id) if self._bot_user_id else None
 
     @property
-    def lock_scope(self) -> str | None:
+    def lock_scope(self) -> LockScope | None:
         return None
 
     @property

src/chat_sdk/adapters/github/adapter.py

@@ -80,7 +80,23 @@ class GitHubAdapterAutoConfig(GitHubAdapterBaseConfig, total=False):
     """Configuration with no auth fields - will auto-detect from env vars."""
 
 
-# Union of all configuration types
+class _GitHubAdapterConfigInternal(GitHubAdapterBaseConfig, total=False):
+    """Internal superset used for duck-typed `config.get(...)` auth detection.
+
+    The public API surface is the auth-mode-specific TypedDicts above — they
+    document which fields are valid for each auth mode. Inside `__init__` we
+    do mode detection via `.get("token")`, `.get("app_id")`, etc., which
+    requires a type that admits every possible key. This type is never
+    exposed to consumers.
+    """
+
+    token: str
+    app_id: str
+    installation_id: int
+    private_key: str
+
+
+# Union of all public configuration types
 GitHubAdapterConfig = (
     GitHubAdapterPATConfig | GitHubAdapterAppConfig | GitHubAdapterMultiTenantAppConfig | GitHubAdapterAutoConfig
 )

src/chat_sdk/adapters/github/types.py

@@ -69,6 +69,7 @@
     FormattedContent,
     ListThreadsOptions,
     ListThreadsResult,
+    LockScope,
     Message,
     RawMessage,
     ReactionEvent,
@@ -130,7 +131,7 @@ def __init__(self, config: GoogleChatAdapterConfig | None = None) -> None:
             config = GoogleChatAdapterConfig()
 
         self._name = "gchat"
-        self._lock_scope: str | None = None
+        self._lock_scope: LockScope | None = None
         self._persist_message_history: bool | None = None
         self._logger: Logger = config.logger or ConsoleLogger("info").child("gchat")
         self._user_name = config.user_name or "bot"
@@ -211,7 +212,7 @@ def bot_user_id(self) -> str | None:
         return self._bot_user_id
 
     @property
-    def lock_scope(self) -> str | None:
+    def lock_scope(self) -> LockScope | None:
         return self._lock_scope
 
     @property

src/chat_sdk/adapters/google_chat/adapter.py

@@ -47,6 +47,7 @@
     FetchOptions,
     FetchResult,
     FormattedContent,
+    LockScope,
     Message,
     MessageMetadata,
     RawMessage,
@@ -169,7 +170,7 @@ def bot_user_id(self) -> str | None:
         return self._bot_user_id
 
     @property
-    def lock_scope(self) -> str | None:
+    def lock_scope(self) -> LockScope | None:
         return None
 
     @property
@@ -537,7 +538,7 @@ async def edit_message(
             ),
         )
 
-    async def delete_message(self, _thread_id: str, message_id: str) -> None:
+    async def delete_message(self, thread_id: str, message_id: str) -> None:
         """Delete a message (delete a comment)."""
         await self._ensure_valid_token()
 
@@ -554,7 +555,7 @@ async def delete_message(self, _thread_id: str, message_id: str) -> None:
 
     async def add_reaction(
         self,
-        _thread_id: str,
+        thread_id: str,
         message_id: str,
         emoji: EmojiValue | str,
     ) -> None:
@@ -575,14 +576,14 @@ async def add_reaction(
 
     async def remove_reaction(
         self,
-        _thread_id: str,
-        _message_id: str,
-        _emoji: EmojiValue | str,
+        thread_id: str,
+        message_id: str,
+        emoji: EmojiValue | str,
     ) -> None:
         """Remove a reaction from a comment (limited support)."""
         self._logger.warn("removeReaction is not fully supported on Linear - reaction ID lookup would be required")
 
-    async def start_typing(self, _thread_id: str, _status: str | None = None) -> None:
+    async def start_typing(self, thread_id: str, status: str | None = None) -> None:
         """Start typing indicator. Not supported by Linear."""
         pass
 

src/chat_sdk/adapters/linear/adapter.py

@@ -73,6 +73,7 @@
     LinkPreview,
     ListThreadsOptions,
     ListThreadsResult,
+    LockScope,
     MemberJoinedChannelEvent,
     Message,
     MessageMetadata,
@@ -203,7 +204,7 @@ def __init__(self, config: SlackAdapterConfig | None = None) -> None:
         self._bot_id: str | None = None  # Bot app ID (B_xxx)
         self._chat: ChatInstance | None = None
         self._format_converter = SlackFormatConverter()
-        self._lock_scope = "thread"
+        self._lock_scope: LockScope = "thread"
         self._persist_message_history = False
 
         # Channel external/shared cache
@@ -245,7 +246,7 @@ def bot_user_id(self) -> str | None:
         return self._bot_user_id
 
     @property
-    def lock_scope(self) -> str:
+    def lock_scope(self) -> LockScope:
         return self._lock_scope
 
     @property

src/chat_sdk/adapters/slack/adapter.py

@@ -45,6 +45,7 @@
     FetchOptions,
     FetchResult,
     FormattedContent,
+    LockScope,
     Message,
     MessageMetadata,
     RawMessage,
@@ -195,7 +196,7 @@ def bot_user_id(self) -> str | None:
         return self._bot_user_id
 
     @property
-    def lock_scope(self) -> str | None:
+    def lock_scope(self) -> LockScope | None:
         return None
 
     @property
@@ -767,23 +768,23 @@ async def delete_message(self, thread_id: str, message_id: str) -> None:
 
     async def add_reaction(
         self,
-        _thread_id: str,
-        _message_id: str,
-        _emoji: EmojiValue | str,
+        thread_id: str,
+        message_id: str,
+        emoji: EmojiValue | str,
     ) -> None:
         """Add a reaction (not supported by Teams Bot Framework API)."""
         self._logger.warn("addReaction is not supported by the Teams Bot Framework API")
 
     async def remove_reaction(
         self,
-        _thread_id: str,
-        _message_id: str,
-        _emoji: EmojiValue | str,
+        thread_id: str,
+        message_id: str,
+        emoji: EmojiValue | str,
     ) -> None:
         """Remove a reaction (not supported by Teams Bot Framework API)."""
         self._logger.warn("removeReaction is not supported by the Teams Bot Framework API")
 
-    async def start_typing(self, thread_id: str, _status: str | None = None) -> None:
+    async def start_typing(self, thread_id: str, status: str | None = None) -> None:
         """Send typing indicator to a Teams conversation."""
         decoded = self.decode_thread_id(thread_id)
 

src/chat_sdk/adapters/teams/adapter.py

@@ -68,6 +68,7 @@
     FetchOptions,
     FetchResult,
     FormattedContent,
+    LockScope,
     Message,
     MessageMetadata,
     RawMessage,
@@ -257,7 +258,7 @@ def __init__(self, config: TelegramAdapterConfig | None = None) -> None:
             )
 
         self._name: str = "telegram"
-        self._lock_scope: str = "channel"
+        self._lock_scope: LockScope = "channel"
         self._persist_message_history: bool = True
 
         self._bot_token: str = bot_token
@@ -300,7 +301,7 @@ def name(self) -> str:
         return self._name
 
     @property
-    def lock_scope(self) -> str:
+    def lock_scope(self) -> LockScope:
         return self._lock_scope
 
     @property
@@ -1018,7 +1019,7 @@ async def remove_reaction(
         self,
         thread_id: str,
         message_id: str,
-        _emoji: EmojiValue | str,
+        emoji: EmojiValue | str,
     ) -> None:
         """Remove a reaction from a Telegram message."""
         parsed_thread = self._resolve_thread_id(thread_id)