feat(chat): add message.subject + fetch_subject adapter hook

Port the core message.subject feature from upstream eb5f94a (PR #459,
"feat(chat): message.subject + adapter client access"). Tracks #98.

Core type system + chat binding only:
- MessageSubject dataclass (snake_case, ~10 fields) + MessageSubjectParty
  for the assignee/author { id, name } sub-objects, mirroring the upstream
  TS MessageSubject interface in packages/chat/src/types.ts.
- Optional fetch_subject(raw) -> MessageSubject | None hook on BaseAdapter
  (default returns None). Declared on BaseAdapter (not the Adapter Protocol)
  to match how every other optional adapter hook is declared here, so
  adapters that don't implement it still satisfy Adapter for type-checking.
- Message.subject async accessor backed by an identity-keyed, weakly-scoped
  adapter registry + cached resolution future (mirrors upstream's adapterMap
  WeakMap and _subjectPromise). Resolved subject is cached so a second
  `await message.subject` does not re-call fetch_subject; raising hooks
  resolve to None (mirrors upstream .catch(() => null)).
- Chat registers the owning adapter at the single dispatch bind site
  (_dispatch_to_handlers), through which every dispatched message flows.

WeakMap hashability decision: Message is a plain @DataClass (eq=True) and
therefore unhashable, so weakref.WeakKeyDictionary[Message, Adapter] raises
TypeError. Rather than change Message's equality contract (eq=False/frozen),
we key a plain dict by id(message) (object identity, matching WeakMap
semantics) and register a weakref.finalize callback per message that pops the
entry on GC. weakref.ref works on a plain dataclass even though hash() does
not, and the finalizer closes the id() reuse hole.

Out of scope (follow-ups): GitHub + Linear adapter implementations of
fetch_subject, which depend on those adapters exposing their native client
(.octokit / .linear_client) — not yet present.

https://claude.ai/code/session_01FyMxQn2BEAzmwKS1GZczKj

Author: claude

src/chat_sdk/__init__.py

@@ -158,6 +158,8 @@
     MessageContext,
     MessageData,
     MessageMetadata,
+    MessageSubject,
+    MessageSubjectParty,
     ModalCloseEvent,
     ModalResponse,
     ModalSubmitEvent,
@@ -368,6 +370,8 @@
     "MessageContext",
     "MessageData",
     "MessageMetadata",
+    "MessageSubject",
+    "MessageSubjectParty",
     "ModalCloseEvent",
     "ModalResponse",
     "ModalSubmitEvent",

src/chat_sdk/chat.py

@@ -63,6 +63,7 @@
     UserInfo,
     WebhookOptions,
     _parse_iso,
+    set_message_adapter,
 )
 
 # ---------------------------------------------------------------------------
@@ -2135,6 +2136,13 @@ async def _dispatch_to_handlers(
         context: MessageContext | None = None,
     ) -> None:
         """Route a message to the correct handler chain."""
+        # Register the owning adapter so handlers can lazily resolve
+        # ``message.subject`` via the adapter's optional ``fetch_subject`` hook.
+        # Mirrors upstream's ``setMessageAdapter`` call at the dispatch bind
+        # site (packages/chat/src/chat.ts). Every dispatched message flows
+        # through here, so this is the single registration point.
+        set_message_adapter(message, adapter)
+
         # Detect mention
         message.is_mention = message.is_mention or self._detect_mention(adapter, message)
 

src/chat_sdk/types.py

@@ -5,6 +5,8 @@
 
 from __future__ import annotations
 
+import asyncio
+import weakref
 from collections.abc import AsyncIterable, Awaitable, Callable
 from dataclasses import dataclass, field
 from datetime import datetime
@@ -387,6 +389,100 @@ class SerializedMessage(_SerializedMessageRequired, total=False):
     links: list[SerializedLinkPreview]
 
 
+@dataclass
+class MessageSubjectParty:
+    """A person referenced by a :class:`MessageSubject` (assignee/author).
+
+    Mirrors the inline ``{ id: string; name: string }`` shape used by
+    upstream's ``MessageSubject.assignee`` / ``MessageSubject.author``.
+    """
+
+    id: str
+    name: str
+
+
+@dataclass
+class MessageSubject:
+    """The external subject a message refers to (e.g. a Linear issue or GitHub PR).
+
+    Python port of the TS ``MessageSubject`` interface
+    (``packages/chat/src/types.ts``). Resolved lazily via
+    :attr:`Message.subject`, which delegates to the owning adapter's
+    optional :meth:`Adapter.fetch_subject` hook.
+
+    Field names are snake_case per the Python port convention; ``raw`` is
+    the platform-specific escape hatch.
+    """
+
+    # ``id`` and ``type`` are the only required fields upstream; everything
+    # else is optional. ``raw`` is required upstream but defaults to ``None``
+    # here so partially-populated subjects (e.g. in tests) construct cleanly.
+    id: str
+    type: str
+    raw: Any = None
+    assignee: MessageSubjectParty | None = None
+    author: MessageSubjectParty | None = None
+    description: str | None = None
+    labels: list[str] | None = None
+    status: str | None = None
+    title: str | None = None
+    url: str | None = None
+
+
+# --------------------------------------------------------------------------
+# Message -> Adapter registry (powers ``Message.subject``)
+# --------------------------------------------------------------------------
+#
+# Upstream (``packages/chat/src/message.ts``) uses
+# ``const adapterMap = new WeakMap<Message, Adapter>()`` so a dispatched
+# message can lazily ask its owning adapter to resolve its subject, without
+# the message holding a hard reference to the adapter and without leaking
+# messages after they fall out of scope.
+#
+# Python port hazard — hashability/weakref:
+#   ``Message`` is a plain ``@dataclass`` (``eq=True``), which makes instances
+#   *unhashable*. A ``weakref.WeakKeyDictionary[Message, Adapter]`` therefore
+#   raises ``TypeError: unhashable type: 'Message'``. We deliberately do NOT
+#   change ``Message`` to ``eq=False``/``frozen=True`` (that would alter its
+#   public equality contract). Instead we key a plain ``dict`` by
+#   ``id(message)`` (object identity, matching ``WeakMap`` semantics) and
+#   register a ``weakref.finalize`` callback per message that pops the entry
+#   when the message is garbage-collected. ``weakref.ref(message)`` works on a
+#   plain dataclass even though ``hash()`` does not, so this is safe. The
+#   finalizer also closes the ``id()`` reuse hole: the entry is removed before
+#   CPython can recycle the id for a new object.
+_message_adapter_map: dict[int, Adapter] = {}
+
+
+def set_message_adapter(message: Message, adapter: Adapter) -> None:
+    """Register the adapter that owns ``message`` (powers ``message.subject``).
+
+    Called by :class:`~chat_sdk.chat.Chat` at the dispatch bind site so every
+    message handed to a handler can resolve its subject via the adapter's
+    optional :meth:`Adapter.fetch_subject` hook.
+
+    Mirrors upstream ``setMessageAdapter`` (``packages/chat/src/message.ts``).
+    The mapping is keyed by object identity and weakly scoped: when ``message``
+    is garbage-collected, its entry is removed automatically.
+    """
+    key = id(message)
+    _message_adapter_map[key] = adapter
+
+    # Drop the entry when the message is GC'd. A zero-arg closure (rather than
+    # ``weakref.finalize(message, dict.pop, key, None)``) captures ``key`` and
+    # keeps the finalizer callable's type unambiguous for the type-checker.
+    # ``pop(key, None)`` is a no-op if the entry was already removed.
+    def _cleanup() -> None:
+        _message_adapter_map.pop(key, None)
+
+    weakref.finalize(message, _cleanup)
+
+
+def _get_message_adapter(message: Message) -> Adapter | None:
+    """Return the adapter registered for ``message``, or ``None``."""
+    return _message_adapter_map.get(id(message))
+
+
 def _strip_none(d: dict[str, Any]) -> dict[str, Any]:
     """Remove keys whose value is ``None`` from a dict.
 
@@ -412,6 +508,63 @@ class Message:
     links: list[LinkPreview] | None = None
     raw: Any = None
 
+    # Cached awaitable for ``subject``. Mirrors upstream's ``_subjectPromise``:
+    # the first ``await message.subject`` stores the in-flight future here so a
+    # second access reuses it instead of re-calling ``fetch_subject``.
+    # ``init=False``/``compare=False``/``repr=False`` keep it out of the
+    # dataclass ``__init__``, equality, and ``repr`` — it is purely internal
+    # resolution state, not message data.
+    _subject_future: Any = field(default=None, init=False, compare=False, repr=False)
+
+    async def _resolve_subject(self) -> MessageSubject | None:
+        """Resolve the subject via the owning adapter's ``fetch_subject`` hook.
+
+        Returns ``None`` when no adapter is registered, the adapter has no
+        ``fetch_subject`` hook, the hook returns ``None``, or the hook raises
+        (failures are swallowed, mirroring upstream's ``.catch(() => null)``).
+        """
+        adapter = _get_message_adapter(self)
+        fetch_subject = getattr(adapter, "fetch_subject", None)
+        if adapter is None or fetch_subject is None:
+            return None
+        try:
+            return await fetch_subject(self.raw)
+        except Exception:
+            return None
+
+    async def _subject(self) -> MessageSubject | None:
+        """Coroutine backing the :attr:`subject` accessor (caches the result).
+
+        The first await schedules ``_resolve_subject`` once via
+        ``ensure_future`` and stores the shared future on the instance; every
+        later/concurrent await reuses it, so ``fetch_subject`` runs at most
+        once. Mirrors upstream's cached ``_subjectPromise``.
+        """
+        if self._subject_future is None:
+            self._subject_future = asyncio.ensure_future(self._resolve_subject())
+        return await self._subject_future
+
+    @property
+    def subject(self) -> Awaitable[MessageSubject | None]:
+        """The external subject this message refers to (issue, PR, etc.), or ``None``.
+
+        Lazily resolved via the owning adapter's optional
+        :meth:`Adapter.fetch_subject` hook. The adapter is registered at
+        dispatch time by :func:`set_message_adapter`.
+
+        Mirrors upstream ``Message.subject`` (``packages/chat/src/message.ts``):
+        it is an awaitable, the result is cached after the first access, and a
+        second ``await message.subject`` does NOT re-call ``fetch_subject``.
+        Concurrent awaits share a single in-flight resolution.
+
+        Usage::
+
+            subject = await message.subject
+            if subject is not None:
+                ...
+        """
+        return self._subject()
+
     def to_json(self) -> dict[str, Any]:
         """Serialize to JSON-compatible dict.
 
@@ -1257,6 +1410,17 @@ async def get_user(self, user_id: str) -> UserInfo | None:
         """
         return None
 
+    # NOTE: ``fetch_subject`` is intentionally NOT declared here. Upstream's
+    # ``Adapter.fetchSubject`` is an *optional* member (``fetchSubject?(...)``),
+    # and in this Python port the established convention for optional adapter
+    # hooks (``stream``, ``open_dm``, ``rehydrate_attachment``,
+    # ``get_channel_visibility``, ...) is to declare them on :class:`BaseAdapter`
+    # only — NOT on this structural ``Protocol`` — so that adapters which don't
+    # implement them still satisfy ``Adapter`` for type-checking. Declaring it
+    # on the Protocol would make it a *required* attribute and break every
+    # adapter that doesn't define it. :attr:`Message.subject` reads the hook via
+    # ``getattr(adapter, "fetch_subject", None)``, so presence is fully optional.
+
 
 class BaseAdapter:
     """Base adapter with default implementations for optional methods.
@@ -1415,6 +1579,22 @@ async def get_user(self, user_id: str) -> UserInfo | None:
         """
         raise ChatNotImplementedError(self.name, "getUser")
 
+    async def fetch_subject(self, raw: Any) -> MessageSubject | None:
+        """Resolve the external subject a message refers to (issue, PR, etc.).
+
+        Optional — the default returns ``None`` (no subject).  Adapters that
+        can resolve a backing entity (a Linear issue, a GitHub PR, etc.) from a
+        message's raw payload should override this.  Unlike most optional
+        :class:`BaseAdapter` hooks it does *not* raise
+        :class:`~chat_sdk.errors.ChatNotImplementedError`, because
+        :attr:`Message.subject` is best-effort: "this adapter has no subject
+        concept" is a normal, non-error outcome that maps to ``None``.
+
+        Mirrors upstream's optional ``Adapter.fetchSubject``
+        (``packages/chat/src/types.ts``).
+        """
+        return None
+
     def rehydrate_attachment(self, attachment: Attachment) -> Attachment:
         """Reconstruct ``fetch_data`` on an attachment after deserialization.
 

tests/test_chat_faithful.py

@@ -34,6 +34,7 @@
     ConcurrencyConfig,
     EmojiValue,
     MessageContext,
+    MessageSubject,
     ModalSubmitEvent,
     QueueEntry,
     ReactionEvent,
@@ -3889,3 +3890,43 @@ async def test_should_not_cache_incoming_messages_when_adapter_does_not_set_pers
 
         history_keys = [k for k in state.cache if k.startswith("msg-history:")]
         assert len(history_keys) == 0
+
+
+class TestSubjectBinding:
+    """Dispatch registers the owning adapter so handlers can resolve message.subject."""
+
+    async def test_handler_can_resolve_subject_via_adapter_hook(self):
+        adapter = create_mock_adapter("slack")
+        expected = MessageSubject(id="ENG-1", type="issue", title="Fix it", raw={})
+
+        async def _fetch_subject(raw):  # noqa: ANN001, ANN202
+            return expected
+
+        adapter.fetch_subject = _fetch_subject  # type: ignore[attr-defined]
+        chat, adapter, state = await _init_chat(adapter=adapter)
+
+        resolved: list[MessageSubject | None] = []
+
+        @chat.on_subscribed_message
+        async def handler(thread, message, context=None):
+            resolved.append(await message.subject)
+
+        await state.subscribe("slack:C123:1234.5678")
+        msg = create_test_message("msg-1", "Follow up")
+        await chat.handle_incoming_message(adapter, "slack:C123:1234.5678", msg)
+
+        assert resolved == [expected]
+
+    async def test_subject_is_none_when_adapter_has_no_fetch_subject_hook(self):
+        chat, adapter, state = await _init_chat()
+        resolved: list[MessageSubject | None] = []
+
+        @chat.on_subscribed_message
+        async def handler(thread, message, context=None):
+            resolved.append(await message.subject)
+
+        await state.subscribe("slack:C123:1234.5678")
+        msg = create_test_message("msg-1", "Follow up")
+        await chat.handle_incoming_message(adapter, "slack:C123:1234.5678", msg)
+
+        assert resolved == [None]