fix: cache PostableObjects in history with real message ID

PostableObject posts (e.g., Plan) now cached in thread/channel message
history using the real adapter-returned message ID and fallback text.
This is an intentional divergence from upstream TS, which skips history
for PostableObjects (a gap, not a design choice — regular posts and
streaming posts both cache, only PostableObjects were missed).

Changes:
- post_postable_object() now returns the RawMessage
- Thread/Channel _handle_postable_object returns RawMessage
- History append uses raw.id (not synthetic "postable-obj" constant)
- Documented as intentional divergence in UPSTREAM_SYNC.md non-parity

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

Author: patrick-chinchill

docs/UPSTREAM_SYNC.md

@@ -392,6 +392,8 @@ stay explicit instead of being rediscovered in code review.
 | `ast_to_plain_text` | Joins blocks with `\n` | Concatenates directly | More readable output |
 | `renderPostable` on unknown input | Returns `str(message)` | Throws `Error` | More resilient |
 | Chat resolver | 3-level: explicit → ContextVar → global | Process-global singleton | See [DECISIONS.md](DECISIONS.md#why-3-level-chat-resolver) |
+| PostableObject history | Cached in message history with real message ID | Not cached (skips history) | Upstream gap — posted messages should appear in thread/channel history |
+| Teams `msteams` transport key | Stripped from action values | Not stripped | Upstream gap — SDK-injected metadata should not leak to handlers |
 
 ### Platform-specific gaps
 

src/chat_sdk/channel.py

@@ -282,10 +282,13 @@ async def post(
         If the message is a PostableObject (e.g. Plan), it is posted via
         native adapter support or fallback text.
         """
-        # Handle PostableObject (e.g. Plan) — returned directly, not cached
-        # in message history (matches upstream TS behavior).
+        # Handle PostableObject (e.g. Plan)
         if is_postable_object(message):
-            await self._handle_postable_object(message)
+            raw = await self._handle_postable_object(message)
+            if self._message_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))
             return message
 
         if _is_async_iterable(message):
@@ -314,7 +317,7 @@ async def _post_single_message(
 
         return sent
 
-    async def _handle_postable_object(self, obj: Any) -> None:
+    async def _handle_postable_object(self, obj: Any) -> Any:
         """Post a PostableObject using native adapter support or fallback."""
         adapter = self.adapter
 
@@ -323,7 +326,7 @@ async def _post_fn(thread_id: str, message: str) -> Any:
                 return await adapter.post_channel_message(thread_id, message)
             return await adapter.post_message(thread_id, message)
 
-        await post_postable_object(obj, adapter, self._id, _post_fn)
+        return await post_postable_object(obj, adapter, self._id, _post_fn)
 
     async def post_ephemeral(
         self,

src/chat_sdk/plan.py

@@ -145,9 +145,12 @@ async def post_postable_object(
     thread_id: str,
     post_fn: Any,
     logger: Logger | None = None,
-) -> None:
+) -> Any:
     """Post a PostableObject using the adapter's native support or fallback text.
 
+    Returns the ``RawMessage`` from the adapter so callers can use the
+    real message ID for history caching.
+
     Parameters
     ----------
     obj:
@@ -176,6 +179,7 @@ def _make_context(raw: Any) -> PostableObjectContext:
     else:
         raw = await post_fn(thread_id, obj.get_fallback_text())
         obj.on_posted(_make_context(raw))
+    return raw
 
 
 # =============================================================================

src/chat_sdk/thread.py

@@ -440,10 +440,15 @@ async def post(
         or a PostableObject (e.g. Plan). PostableObjects are returned directly
         after posting so the caller can continue to mutate them.
         """
-        # Handle PostableObject (e.g. Plan) — returned directly, not cached
-        # in message history (matches upstream TS behavior).
+        # Handle PostableObject (e.g. Plan)
         if is_postable_object(message):
-            await self._handle_postable_object(message)
+            raw = await self._handle_postable_object(message)
+            # Cache in history with the real message ID (upstream skips this,
+            # but that's a gap — posted messages should appear in history).
+            if self._message_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))
             return message
 
         # Handle AsyncIterable (streaming)
@@ -459,9 +464,9 @@ async def post(
 
         return result
 
-    async def _handle_postable_object(self, obj: Any) -> None:
+    async def _handle_postable_object(self, obj: Any) -> Any:
         """Post a PostableObject using native adapter support or fallback."""
-        await post_postable_object(
+        return await post_postable_object(
             obj,
             self.adapter,
             self._id,