feat(chat): Transcripts API + rename message history cache to thread_history (vercel/chat#448)

Port of upstream 46d183b (chat@4.29.0).

Rename (with back-compat, mirroring upstream):
- message_history.py -> thread_history.py; MessageHistoryCache ->
  ThreadHistoryCache. Old module path kept as a deprecated re-export shim.
- ChatConfig.thread_history added; deprecated ChatConfig.message_history
  still read, thread_history wins when both are set.
- Adapter.persist_thread_history added; deprecated persist_message_history
  still honored (either flag enables persistence). Telegram and WhatsApp
  adapters switch to the new flag, matching upstream.
- State storage key prefix "msg-history:" is deliberately unchanged so
  existing persisted data is not orphaned.

New Transcripts API:
- transcripts.py: TranscriptsApiImpl (append/list/count/delete) keyed by a
  cross-platform user key, backed by StateAdapter.append_to_list. delete()
  writes a tombstone via append_to_list(max_length=1) because state.delete
  only addresses the k/v namespace on non-memory adapters.
- ChatConfig.transcripts + ChatConfig.identity (IdentityResolver); the
  constructor raises when transcripts is set without identity. Inbound
  dispatch resolves message.user_key once per message via the resolver.
- chat.transcripts accessor raises when not configured (fail loudly).
- New types: TranscriptEntry, TranscriptsConfig, TranscriptRole,
  AppendInput, AppendOptions, ListQuery, CountQuery, DeleteTarget,
  DeleteResult, IdentityContext, IdentityResolver, DurationString.

Tests: test_message_history.py renamed to test_thread_history.py (names
aligned to thread-history.test.ts titles, deprecated-alias test added);
chat.test.ts persistThreadHistory block ported into test_chat_faithful.py;
new test_transcripts.py and test_transcripts_wiring.py port
transcripts.test.ts and transcripts-wiring.test.ts 1:1.

https://claude.ai/code/session_013zwTcMek5rNqBTQvs2oF64
(cherry picked from commit 765420dc4d21804b19f1d8eccddebc3a392b0e61)

Author: claude

src/chat_sdk/__init__.py

@@ -65,6 +65,8 @@
 from chat_sdk.errors import ChatError, ChatNotImplementedError, LockError, RateLimitError, StateNotConnectedError
 from chat_sdk.from_full_stream import from_full_stream
 from chat_sdk.logger import ConsoleLogger, Logger, LogLevel
+
+# Deprecated aliases — renamed to ThreadHistoryCache / ThreadHistoryConfig.
 from chat_sdk.message_history import MessageHistoryCache, MessageHistoryConfig
 from chat_sdk.modals import (
     ExternalSelect,
@@ -121,10 +123,13 @@
 from chat_sdk.shared.streaming_markdown import StreamingMarkdownRenderer
 from chat_sdk.state.memory import MemoryStateAdapter
 from chat_sdk.thread import ThreadImpl
+from chat_sdk.thread_history import ThreadHistoryCache, ThreadHistoryConfig
 from chat_sdk.types import (
     ActionEvent,
     Adapter,
     AdapterPostableMessage,
+    AppendInput,
+    AppendOptions,
     AppHomeOpenedEvent,
     AssistantContextChangedEvent,
     AssistantThreadStartedEvent,
@@ -138,6 +143,10 @@
     ChatInstance,
     ConcurrencyConfig,
     ConcurrencyStrategy,
+    CountQuery,
+    DeleteResult,
+    DeleteTarget,
+    DurationString,
     EmojiFormats,
     EmojiValue,
     EphemeralMessage,
@@ -146,7 +155,10 @@
     FetchResult,
     FileUpload,
     FormattedContent,
+    IdentityContext,
+    IdentityResolver,
     LinkPreview,
+    ListQuery,
     ListThreadsOptions,
     ListThreadsResult,
     Lock,
@@ -185,6 +197,10 @@
     Thread,
     ThreadInfo,
     ThreadSummary,
+    TranscriptEntry,
+    TranscriptRole,
+    TranscriptsApi,
+    TranscriptsConfig,
     UserInfo,
     WebhookOptions,
     WellKnownEmoji,
@@ -298,7 +314,10 @@
     "ConsoleLogger",
     "Logger",
     "LogLevel",
-    # Message history
+    # Thread history (per-thread cache)
+    "ThreadHistoryCache",
+    "ThreadHistoryConfig",
+    # Thread history — deprecated aliases (renamed upstream)
     "MessageHistoryCache",
     "MessageHistoryConfig",
     # Modal builders (PascalCase primary — matches source TS SDK)
@@ -335,6 +354,8 @@
     "ActionEvent",
     "Adapter",
     "AdapterPostableMessage",
+    "AppendInput",
+    "AppendOptions",
     "AppHomeOpenedEvent",
     "AssistantContextChangedEvent",
     "AssistantThreadStartedEvent",
@@ -348,6 +369,10 @@
     "ChatInstance",
     "ConcurrencyConfig",
     "ConcurrencyStrategy",
+    "CountQuery",
+    "DeleteResult",
+    "DeleteTarget",
+    "DurationString",
     "EmojiFormats",
     "EmojiValue",
     "EphemeralMessage",
@@ -356,7 +381,10 @@
     "FetchResult",
     "FileUpload",
     "FormattedContent",
+    "IdentityContext",
+    "IdentityResolver",
     "LinkPreview",
+    "ListQuery",
     "ListThreadsOptions",
     "ListThreadsResult",
     "Lock",
@@ -396,6 +424,10 @@
     "Thread",
     "ThreadInfo",
     "ThreadSummary",
+    "TranscriptEntry",
+    "TranscriptRole",
+    "TranscriptsApi",
+    "TranscriptsConfig",
     "UserInfo",
     "WebhookOptions",
     "WellKnownEmoji",

src/chat_sdk/adapters/teams/adapter.py

@@ -1700,7 +1700,7 @@ async def _close_stream_session(
             # from typing indicator to message bubble; if that send fails
             # the streaming UI may stay until Teams times the session out
             # client-side, but the recorded ``SentMessage`` and
-            # ``_message_history`` entry still match what the user saw.
+            # ``_thread_history`` entry still match what the user saw.
             self._logger.warn(
                 "Teams stream final activity failed",
                 {"threadId": thread_id, "error": str(exc)},

src/chat_sdk/adapters/telegram/adapter.py

@@ -594,7 +594,7 @@ def __init__(self, config: TelegramAdapterConfig | None = None) -> None:
 
         self._name: str = "telegram"
         self._lock_scope: LockScope = "channel"
-        self._persist_message_history: bool = True
+        self._persist_thread_history: bool = True
 
         self._bot_token: str = bot_token
         self._api_base_url: str = _trim_trailing_slashes(
@@ -640,8 +640,8 @@ def lock_scope(self) -> LockScope:
         return self._lock_scope
 
     @property
-    def persist_message_history(self) -> bool:
-        return self._persist_message_history
+    def persist_thread_history(self) -> bool:
+        return self._persist_thread_history
 
     @property
     def bot_user_id(self) -> str | None:

src/chat_sdk/adapters/whatsapp/adapter.py

@@ -112,7 +112,7 @@ class WhatsAppAdapter:
     def __init__(self, config: WhatsAppAdapterConfig) -> None:
         self._name = "whatsapp"
         self._lock_scope: LockScope = "channel"
-        self._persist_message_history = True
+        self._persist_thread_history = True
         self._user_name = config.user_name
         self._access_token = config.access_token
         self._app_secret = config.app_secret
@@ -137,8 +137,8 @@ def lock_scope(self) -> LockScope:
         return self._lock_scope
 
     @property
-    def persist_message_history(self) -> bool:
-        return self._persist_message_history
+    def persist_thread_history(self) -> bool:
+        return self._persist_thread_history
 
     @property
     def user_name(self) -> str:

src/chat_sdk/channel.py

@@ -83,7 +83,7 @@ class _ChannelImplConfigWithAdapter:
     state_adapter: StateAdapter
     channel_visibility: ChannelVisibility = "unknown"
     is_dm: bool = False
-    message_history: Any = None
+    thread_history: Any = None
 
 
 @dataclass
@@ -122,15 +122,15 @@ def __init__(self, config: _ChannelImplConfig) -> None:
             self._adapter: Adapter | None = None
             self._adapter_name: str | None = config.adapter_name
             self._state_adapter_instance: StateAdapter | None = None
-            self._message_history: Any = None
+            self._thread_history: Any = None
         else:
             # _ChannelImplConfigWithAdapter, _ChannelImplConfigForThread,
             # or _ChannelImplConfigForChat (from chat.py) -- all have
-            # adapter, state_adapter, and optional message_history attrs.
+            # adapter, state_adapter, and optional thread_history attrs.
             self._adapter = config.adapter  # type: ignore[union-attr]
             self._adapter_name = None
             self._state_adapter_instance = config.state_adapter  # type: ignore[union-attr]
-            self._message_history = getattr(config, "message_history", None)
+            self._thread_history = getattr(config, "thread_history", None)
 
     # -- Properties ----------------------------------------------------------
 
@@ -206,7 +206,7 @@ async def messages(self) -> AsyncIterator[Message]:
         """
         adapter = self.adapter
         channel_id = self._id
-        message_history = self._message_history
+        thread_history = self._thread_history
         cursor: str | None = None
         yielded_any = False
 
@@ -227,8 +227,8 @@ async def messages(self) -> AsyncIterator[Message]:
             cursor = result.next_cursor
 
         # Fallback to cached history
-        if not yielded_any and message_history is not None:
-            cached: list[Message] = await message_history.get_messages(channel_id)
+        if not yielded_any and thread_history is not None:
+            cached: list[Message] = await thread_history.get_messages(channel_id)
             for msg in reversed(cached):
                 yield msg
 
@@ -285,10 +285,10 @@ async def post(
         # Handle PostableObject (e.g. Plan)
         if is_postable_object(message):
             raw = await self._handle_postable_object(message)
-            if self._message_history is not None and raw is not None:
+            if self._thread_history is not None and raw is not None:
                 fallback = message.get_fallback_text() if hasattr(message, "get_fallback_text") else ""
                 sent = self._create_sent_message(raw.id, PostableMarkdown(markdown=fallback), raw.thread_id)
-                await self._message_history.append(self._id, _to_message(sent))
+                await self._thread_history.append(self._id, _to_message(sent))
             return message
 
         if _is_async_iterable(message):
@@ -312,8 +312,8 @@ async def _post_single_message(
 
         sent = self._create_sent_message(raw_msg.id, postable, raw_msg.thread_id)
 
-        if self._message_history is not None:
-            await self._message_history.append(self._id, _to_message(sent))
+        if self._thread_history is not None:
+            await self._thread_history.append(self._id, _to_message(sent))
 
         return sent
 
@@ -439,11 +439,11 @@ def from_json(
 
             # Validation passed — safe to invalidate.
             # Both `_state_adapter_instance` (old chat's state backend)
-            # and `_message_history` (old chat's cache) would route to
+            # and `_thread_history` (old chat's cache) would route to
             # the previous context otherwise.
             if adapter is not None or chat is not None:
                 channel._state_adapter_instance = None
-                channel._message_history = None
+                channel._thread_history = None
         else:
             # Explicit None-checks (not `or`) to avoid the truthiness trap:
             # `""` is a valid-but-falsy value that shouldn't silently fall