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

[patrick-chinchill]

Ports the core message.subject feature from upstream eb5f94a (vercel/chat PR #459, feat(chat): message.subject + adapter client access, chat@4.29.0).

Worklist item P0-1. Tracks #98.

What's ported (CORE type system + chat binding only)

• MessageSubject dataclass in src/chat_sdk/types.py — snake_case mirror of upstream's TS MessageSubject interface (id, type, raw, assignee, author, description, labels, status, title, url). Plus a small MessageSubjectParty dataclass for the { id, name } shape upstream uses inline for assignee/author. Typed dataclass, not a raw dict.
• Optional fetch_subject(raw) -> MessageSubject | None adapter hook on BaseAdapter (default returns None). See the Protocol-placement note below.
• Message.subject async accessor backed by upstream's WeakMap + _subjectPromise pattern:
  • lazily resolves via the owning adapter's fetch_subject;
  • returns None when no adapter is registered, the adapter has no hook, the hook returns None, or the hook raises (failures swallowed, mirroring upstream .catch(() => null));
  • caches the resolved value — a second await message.subject does NOT re-call fetch_subject; concurrent awaits share one in-flight resolution.
• Chat bind site: Chat._dispatch_to_handlers registers the owning adapter for every dispatched message via set_message_adapter. This is the single convergence point all dispatch paths (subscribed / mention / DM / pattern / queue / debounce / burst / rehydrated) flow through — upstream calls setMessageAdapter in 3 scattered spots (handleIncomingMessage + two rehydrateMessage branches), all of which reach this method here.

WeakMap hashability decision (the load-bearing call)

Upstream uses const adapterMap = new WeakMap<Message, Adapter>() — weak on the Message key, strong on the Adapter value, keyed by object identity.

Message in this repo is a plain @dataclass (eq=True), which makes instances unhashable (verified: hash(msg) raises TypeError, and weakref.WeakKeyDictionary[Message, Adapter] raises TypeError: unhashable type: 'Message'). weakref.ref(msg) does work on a plain dataclass.

Chosen approach: a plain dict[int, Adapter] keyed by id(message) + a per-message weakref.finalize callback that pops the entry on GC.

• Preserves upstream's weak-on-key semantics: when the Message is garbage-collected, the entry is removed automatically (verified with a GC test).
• Keyed by object identity (id()), matching WeakMap.
• The finalizer closes the id()-reuse hole — the entry is removed before CPython can recycle the id.
• We deliberately do not switch Message to eq=False/frozen=True, which would have restored an identity hash but silently changed Message's public equality contract (and WeakValueDictionary is the wrong shape — it would weakly hold the long-lived Adapter, not the Message).

The cache (_subject_future) is a dataclass field with init=False, compare=False, repr=False, so it stays out of __init__, equality, and repr. The accessor returns a fresh coroutine each access (so await msg.subject works repeatedly and asyncio.run(msg.subject) is valid) while sharing a single ensure_future-scheduled resolution underneath.

Protocol placement note

fetch_subject is declared on BaseAdapter only, NOT on the Adapter Protocol. Adding it to the structural Protocol makes it a required attribute and breaks every adapter that doesn't define it (pyrefly flagged 36 such errors). This matches how every other optional hook here (stream, open_dm, rehydrate_attachment, get_channel_visibility, ...) is declared — on BaseAdapter, not the Protocol. Message.subject reads the hook via getattr(adapter, "fetch_subject", None), so presence is fully optional regardless of base class.

Follow-ups (out of scope)

• GitHub adapter fetch_subject — depends on the adapter exposing its native .octokit client (doesn't exist yet).
• Linear adapter fetch_subject — depends on the adapter exposing its native .linear_client (doesn't exist yet).

Both are the "adapter client access" half of upstream #459 and are deferred until those adapters expose their native clients.

Tests

tests/test_types.py:

• TestMessageSubjectDataclass — minimal required fields, all fields incl. nested MessageSubjectParty.
• TestMessageSubject (mirrors upstream message.test.ts describe("subject")): None when no adapter; None when adapter has no fetch_subject; returns adapter result; awaited twice -> called once; null result cached; concurrent access shares one call; raising hook -> None; raw payload passed through.
• TestSetMessageAdapterWeakref — registration doesn't crash on unhashable Message; entry removed on GC; distinct messages map to distinct adapters.

tests/test_chat_faithful.py:

• TestSubjectBinding — handler resolves message.subject via the adapter hook after real dispatch; None when the adapter has no hook.

Validation

• uv run ruff check src/ tests/ — All checks passed
• uv run ruff format --check src/ tests/ — 195 files already formatted
• uv run python scripts/audit_test_quality.py — Hard failures: 0
• uv run pytest tests/ -q — 4062 passed, 3 skipped (no regressions)
• uv run pyrefly check — 0 errors (matches origin/main baseline; no new errors)

scripts/verify_test_fidelity.py --strict is not runnable in this environment (the upstream chat@4.29.0 checkout moved ai.test.ts into ai/, so the script's 4.26.0-pinned path resolution fails identically on untouched origin/main); message.test.ts is not in its MAPPING scope. CHANGELOG / pyproject.toml intentionally untouched (cut PR handles versioning).

https://claude.ai/code/session_01FyMxQn2BEAzmwKS1GZczKj

---

Generated by Claude Code

[coderabbitai]

Warning

Review limit reached

@patrick-chinchill, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 53 minutes and 55 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 7045b527-34e7-4677-a4ce-55aa02e903a4

📥 Commits

Reviewing files that changed from the base of the PR and between b5fc8b8 and ac956e1.

📒 Files selected for processing (5)

• src/chat_sdk/__init__.py
• src/chat_sdk/chat.py
• src/chat_sdk/types.py
• tests/test_chat_faithful.py
• tests/test_types.py

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Code Review

This pull request introduces the MessageSubject and MessageSubjectParty dataclasses to represent external subjects associated with messages, along with a weakly-scoped registry mapping Message objects to their owning Adapter to lazily resolve and cache these subjects. Feedback on the changes suggests preventing duplicate finalizer registrations when registering a message adapter multiple times, and reordering the adapter checks to ensure adapter is verified as not None before attempting to retrieve its fetch_subject attribute.

[gemini-code-assist]

If set_message_adapter is called multiple times for the same message object, a new finalizer is registered on each call. This can lead to an accumulation of duplicate finalizer objects and closures, causing unnecessary memory overhead. Checking if the message is already registered before creating a new finalizer prevents this duplicate registration.

Suggested change

	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)
	key = id(message)
	already_registered = key in _message_adapter_map
	_message_adapter_map[key] = adapter
	if not already_registered:
	# 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)

[gemini-code-assist]

When adapter is None, calling getattr(adapter, "fetch_subject", None) is unnecessary and can be confusing, even though getattr(None, ...) technically returns the default value in Python. It is cleaner, safer, and more idiomatic to perform the adapter is None check first before attempting to retrieve any attributes from it. Additionally, when checking for optional values that can be falsy but valid, ensure you use explicit is not None (or is None) checks instead of truthiness checks.

        adapter = _get_message_adapter(self)
        if adapter is None:
            return None
        fetch_subject = getattr(adapter, "fetch_subject", None)
        if fetch_subject is None:
            return None

References

1. When checking for optional values that can be falsy but valid (e.g., 0, empty string, empty list), use is not None instead of a truthiness check to avoid silently ignoring them.

[patrick-chinchill]

@codex review

---

Generated by Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fd9293122f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Shield cached subject lookup from caller cancellation

When a caller awaits message.subject through a timeout/cancelled handler, cancellation propagates into the cached _subject_future because it is awaited directly. For example, await asyncio.wait_for(message.subject, ...) on a slow fetch_subject cancels the shared task; every later await message.subject then raises CancelledError instead of retrying or resolving to None, so one timed-out handler permanently poisons that Message's subject accessor. Consider shielding the shared task or clearing the cache when it is cancelled.

Useful? React with 👍 / 👎.

[patrick-chinchill]

@GHCodex review

---

Generated by Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 66405461a0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Bind skipped context messages before dispatch

When queue/burst drains collapse multiple messages, only the latest message passed to _dispatch_to_handlers is registered here; the earlier messages are delivered to handlers as context.skipped without ever calling set_message_adapter (they were only enqueued while the lock was busy). In that scenario, await context.skipped[0].subject always resolves to None even when the adapter implements fetch_subject, so handlers cannot use the new subject accessor on skipped messages preserved by the concurrency context. Register the skipped messages in the context with the same adapter before invoking handlers.

Useful? React with 👍 / 👎.