feat: 3-level Chat resolver (ContextVar → global → error)

Replace the process-global singleton with a 3-level resolution:
1. ContextVar for current async context (via chat.activate())
2. Process-global default (via chat.register_singleton())
3. RuntimeError if neither set

This gives Python-friendly async isolation without breaking upstream
TS parity. Existing code using register_singleton() is unchanged.

Changes:
- thread.py: _active_chat ContextVar + updated get_chat_singleton()
- chat.py: Chat.activate() context manager returns _ChatActivation
- ThreadImpl.from_json() and ChannelImpl.from_json() accept optional
  chat= parameter for explicit resolution without singleton lookup

Usage:
    # Global (existing pattern, still works)
    chat.register_singleton()

    # Context-local (new, preferred for tests/multi-chat)
    with chat.activate():
        thread = ThreadImpl.from_json(data)

    # Explicit (new, most specific)
    thread = ThreadImpl.from_json(data, chat=chat)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: patrick-chinchill

src/chat_sdk/channel.py

@@ -373,11 +373,18 @@ def from_json(
         cls,
         data: dict[str, Any],
         adapter: Adapter | None = None,
+        chat: Any = None,
     ) -> ChannelImpl:
         """Reconstruct a ChannelImpl from serialized JSON data.
 
-        Accepts both camelCase (canonical output of ``to_json()``) and
-        snake_case keys for backward compatibility.
+        Parameters
+        ----------
+        data:
+            Serialized channel dict (camelCase or snake_case keys accepted).
+        adapter:
+            Explicit adapter. Skips singleton lookup.
+        chat:
+            Explicit Chat instance for adapter/state resolution.
         """
         channel = cls(
             _ChannelImplConfigLazy(
@@ -389,6 +396,11 @@ def from_json(
         )
         if adapter is not None:
             channel._adapter = adapter
+        elif chat is not None:
+            adapter_name = data.get("adapterName") or data.get("adapter_name", "")
+            if adapter_name:
+                channel._adapter = chat.get_adapter(adapter_name)
+            channel._state_adapter_instance = chat.get_state()
         return channel
 
     @classmethod

src/chat_sdk/chat.py

@@ -9,6 +9,7 @@
 from __future__ import annotations
 
 import asyncio
+import contextvars
 import dataclasses
 import re
 import uuid
@@ -22,6 +23,7 @@
 from chat_sdk.logger import ConsoleLogger, Logger
 from chat_sdk.thread import (
     ThreadImpl,
+    _active_chat,
     _ThreadImplConfig,
     get_chat_singleton,
     has_chat_singleton,
@@ -197,6 +199,28 @@ def _create_task(
         return None
 
 
+# ---------------------------------------------------------------------------
+# Chat activation context manager
+# ---------------------------------------------------------------------------
+
+
+class _ChatActivation:
+    """Context manager that sets a Chat as the active instance for the current context."""
+
+    def __init__(self, chat: Chat) -> None:
+        self._chat = chat
+        self._token: contextvars.Token[Any] | None = None
+
+    def __enter__(self) -> Chat:
+        self._token = _active_chat.set(self._chat)  # type: ignore[arg-type]
+        return self._chat
+
+    def __exit__(self, *_: Any) -> None:
+        if self._token is not None:
+            _active_chat.reset(self._token)
+            self._token = None
+
+
 # ---------------------------------------------------------------------------
 # Chat class
 # ---------------------------------------------------------------------------
@@ -339,6 +363,22 @@ def get_singleton() -> Chat:
     def has_singleton() -> bool:
         return has_chat_singleton()
 
+    def activate(self) -> _ChatActivation:
+        """Set this Chat as the active instance for the current async context.
+
+        Usage::
+
+            with chat.activate():
+                # Thread/Channel deserialization resolves to this chat
+                thread = ThreadImpl.from_json(data)
+
+        This is preferred over ``register_singleton()`` when multiple Chat
+        instances coexist (e.g., in tests, multi-tenant servers). The
+        activation is scoped to the current :class:`contextvars.Context`,
+        so concurrent async tasks don't interfere.
+        """
+        return _ChatActivation(self)
+
     # ========================================================================
     # ChatInstance protocol implementation
     # ========================================================================

src/chat_sdk/thread.py

@@ -8,6 +8,7 @@
 from __future__ import annotations
 
 import asyncio
+import contextvars
 from collections.abc import AsyncIterator
 from dataclasses import dataclass
 from datetime import datetime, timezone
@@ -47,10 +48,11 @@
 
 
 # ---------------------------------------------------------------------------
-# Singleton access (mirrors chat-singleton.ts)
+# Chat resolver: ContextVar → process-global → error
 # ---------------------------------------------------------------------------
 
-_singleton: _ChatSingleton | None = None
+_default_chat: _ChatSingleton | None = None
+_active_chat: contextvars.ContextVar[_ChatSingleton | None] = contextvars.ContextVar("_active_chat", default=None)
 
 
 class _ChatSingleton:
@@ -61,23 +63,35 @@ def get_state(self) -> StateAdapter: ...
 
 
 def set_chat_singleton(chat: _ChatSingleton) -> None:
-    global _singleton
-    _singleton = chat
+    """Register *chat* as the process-global default."""
+    global _default_chat
+    _default_chat = chat
 
 
 def get_chat_singleton() -> _ChatSingleton:
-    if _singleton is None:
-        raise RuntimeError("No Chat singleton registered. Call chat.register_singleton() first.")
-    return _singleton
+    """Resolve the active Chat instance.
+
+    Resolution order:
+    1. ContextVar for the current async task (set via ``chat.activate()``)
+    2. Process-global default (set via ``set_chat_singleton()``)
+    3. Raise RuntimeError
+    """
+    ctx = _active_chat.get()
+    if ctx is not None:
+        return ctx
+    if _default_chat is not None:
+        return _default_chat
+    raise RuntimeError("No Chat instance available. Use chat.activate() or register a singleton.")
 
 
 def has_chat_singleton() -> bool:
-    return _singleton is not None
+    return _active_chat.get() is not None or _default_chat is not None
 
 
 def clear_chat_singleton() -> None:
-    global _singleton
-    _singleton = None
+    global _default_chat
+    _default_chat = None
+    _active_chat.set(None)
 
 
 # ---------------------------------------------------------------------------
@@ -687,12 +701,20 @@ def from_json(
         cls,
         data: dict[str, Any],
         adapter: Adapter | None = None,
+        chat: Any = None,
     ) -> ThreadImpl:
         """Reconstruct a ThreadImpl from serialized JSON data.
 
-        Accepts both camelCase (canonical output of ``to_json()``) and
-        snake_case keys for backward compatibility.
-        Uses lazy resolution from the Chat singleton unless an adapter is provided.
+        Parameters
+        ----------
+        data:
+            Serialized thread dict (camelCase or snake_case keys accepted).
+        adapter:
+            Explicit adapter to use. Skips singleton lookup for adapter resolution.
+        chat:
+            Explicit Chat instance. If provided, adapter and state are resolved
+            from this instance instead of the singleton. Useful in multi-chat
+            or test scenarios.
         """
         current_msg_raw = data.get("currentMessage") or data.get("current_message")
         current_msg = None
@@ -711,6 +733,11 @@ def from_json(
         )
         if adapter is not None:
             thread._adapter = adapter
+        elif chat is not None:
+            adapter_name = data.get("adapterName") or data.get("adapter_name")
+            if adapter_name:
+                thread._adapter = chat.get_adapter(adapter_name)
+            thread._state_adapter_instance = chat.get_state()
         return thread
 
     @classmethod