sync: upstream Vercel Chat v4.25.0

Port all 5 changes from upstream v4.25.0:

- feat: Plan/PostableObject blocks for threads (new plan.py module)
- feat: StreamingMarkdownRenderer wrap_tables_for_append option (Slack
  disables code-fencing since it now supports native markdown tables)
- feat: Teams Select/RadioSelect card rendering (Adaptive Card ChoiceSet)
- feat: GitHub issue comment threads (github:owner/repo:issue:42 format)
- fix: Slack OAuth redirect_uri handling

New versioning scheme:
- 0.{upstream_minor}.{patch} — our 0.25.0 = synced to upstream 4.25.0
- UPSTREAM_PARITY constant in __init__.py for programmatic access
- Sync procedure documented in UPSTREAM_SYNC.md

Updated docs:
- CLAUDE.md: version mapping, thread ID formats, message handling flow,
  full validation command
- UPSTREAM_SYNC.md: step-by-step sync procedure with checklist
- CHANGELOG.md: public-facing release notes

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

Author: patrick-chinchill

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.25.0 (2026-04-10)
+
+Synced to [Vercel Chat 4.25.0](https://github.com/vercel/chat). New versioning: our minor version matches the upstream minor version.
+
+### New features (from upstream 4.25.0)
+- **Plan blocks**: `Plan` PostableObject for structured task lists with live updates. Post a plan to a thread, then `add_task()`, `update_task()`, and `complete()` with automatic card rendering.
+- **Streaming table option**: `StreamingMarkdownRenderer(wrap_tables_for_append=False)` disables code-fence wrapping for platforms with native table support. Slack adapter now uses this by default.
+- **Teams Select/RadioSelect**: `Select` and `RadioSelect` card elements now render as Adaptive Card `Input.ChoiceSet` with auto-injected submit button.
+- **GitHub issue threads**: `issue_comment` webhooks on plain issues (not just PRs) now create threads with format `github:owner/repo:issue:42`.
+- **Slack OAuth redirect fix**: `handle_oauth_callback` correctly forwards `redirect_uri` option.
+
+### Versioning
+- Version scheme changed from `0.0.1aX` to `0.{upstream_minor}.{patch}`
+- `UPSTREAM_PARITY` constant in `chat_sdk.__init__` for programmatic access
+- Sync procedure documented in [UPSTREAM_SYNC.md](docs/UPSTREAM_SYNC.md)
+
 ## 0.0.1a12 (2026-04-10)
 
 Python 3.10 support, async-safe Chat resolver, and a large correctness audit.

CLAUDE.md

@@ -1,23 +1,57 @@
 # Claude Code Quick Reference -- chat-sdk-python
 
 ## What is this?
-Python port of Vercel Chat SDK. Multi-platform async chat framework.
+Python port of [Vercel Chat SDK](https://github.com/vercel/chat) (v4.25.0). Multi-platform async chat framework.
 
 ## Key Commands
-- `uv sync --group dev` -- install dependencies
-- `uv run pytest tests/ -q` -- run tests
-- `uv run ruff check src/` -- lint
-- `uv run ruff format src/` -- format
+```bash
+uv sync --group dev           # install dependencies
+uv run pytest tests/ -q       # run tests
+uv run ruff check src/ tests/ scripts/  # lint
+uv run ruff format src/ tests/ scripts/ # format
+
+# Full validation — run before declaring any task done
+uv run ruff check src/ tests/ scripts/ && \
+uv run ruff format --check src/ tests/ scripts/ && \
+uv run python scripts/audit_test_quality.py && \
+uv run python scripts/verify_test_fidelity.py && \
+uv run pytest tests/ --tb=short -q
+```
+
+## Version Mapping
+Our version tracks the upstream Vercel Chat minor version:
+- `0.25.0` = synced to upstream `4.25.0`
+- `0.25.1` = Python-only fixes on top of `4.25.0`
+- `0.26.0` = synced to upstream `4.26.0`
+- `UPSTREAM_PARITY` constant in `__init__.py` = programmatic access
 
 ## Architecture
-- `src/chat_sdk/chat.py` -- Main Chat orchestrator (handlers, routing, concurrency)
+- `src/chat_sdk/chat.py` -- Chat orchestrator (handlers, routing, concurrency)
 - `src/chat_sdk/thread.py` -- Thread (streaming, pagination, subscriptions)
 - `src/chat_sdk/channel.py` -- Channel (thread listing, metadata)
+- `src/chat_sdk/plan.py` -- Plan (PostableObject for structured task lists)
 - `src/chat_sdk/types.py` -- All types (Message, Author, Adapter protocol)
 - `src/chat_sdk/adapters/` -- 8 platform adapters
 - `src/chat_sdk/shared/` -- Markdown parser, format converter, streaming renderer
 - `src/chat_sdk/state/` -- Memory, Redis, Postgres backends
-- `tests/` -- 3,267 tests
+- `tests/` -- 3,400+ tests
+
+### Thread ID Format
+All thread IDs follow: `{adapter}:{channel}:{thread}`
+- Slack: `slack:C123ABC:1234567890.123456`
+- Teams: `teams:{base64(conversationId)}:{base64(serviceUrl)}`
+- Google Chat: `gchat:spaces/ABC123:{base64(threadName)}`
+- Discord: `discord:{guildId}:{channelId}[:{threadId}]`
+- GitHub: `github:owner/repo:42` (PR) or `github:owner/repo:issue:42`
+
+### Message Handling Flow
+1. Platform sends webhook → adapter verifies + parses
+2. Adapter calls `chat.process_message()` (or `process_action`, etc.)
+3. Chat acquires lock, deduplicates, then routes:
+   - Subscribed thread → `on_subscribed_message` handlers
+   - @mention → `on_mention` handlers
+   - DM → `on_direct_message` handlers
+   - Pattern match → `on_message` handlers
 
 ## Principles
 
@@ -31,25 +65,22 @@ Python port of Vercel Chat SDK. Multi-platform async chat framework.
 
 ## Port Rules (TS → Python)
 
-These are specific patterns that broke during the port. The principles above
-explain *why*; these explain *what to watch for*.
+See docs/UPSTREAM_SYNC.md for the full 15-hazard guide. Key patterns:
 
-- `datetime.utcnow()` → `datetime.now(tz=UTC)` (deprecated, naive)
-- `asyncio.ensure_future` → `loop.create_task()` (deprecated)
+- `x or default` → `x if x is not None else default` (truthiness trap)
+- `datetime.utcnow()` → `datetime.now(tz=timezone.utc)` (deprecated, naive)
 - Raw dicts to `process_*` → typed dataclasses (ActionEvent, etc.)
-- camelCase dispatch keys → snake_case
+- camelCase dispatch keys → snake_case internally, camelCase at serialization boundary
 - `random.choices` for tokens → `secrets.token_hex`
-- Optional deps at module level → lazy import
+- Optional deps at module level → lazy import inside methods
 - `==` for signatures → `hmac.compare_digest`
-- `or` for empty-string-valid fields → `is not None`
 - Validate external URLs before requests (SSRF)
-- Check `extend_lock` return value in loops
-
-## Adding a New Adapter
-See docs/ARCHITECTURE.md and CONTRIBUTING.md.
+- `chat.activate()` > `register_singleton()` > error (3-level resolver)
 
 ## Upstream Sync
-See docs/UPSTREAM_SYNC.md for TS->Python translation patterns.
+
+See docs/UPSTREAM_SYNC.md for the full sync procedure, porting hazards, review
+checklist, and known non-parity list.
 
 ## Known Limitations
 - Markdown parser handles common cases but is not full CommonMark
@@ -63,5 +94,5 @@ async mock bugs, and cross-file duplicates. PRs that introduce hard failures
 will not pass CI.
 
 **Fidelity check** (`scripts/verify_test_fidelity.py`) verifies every TS
-`it("...")` has a matching Python `def test_*()`. Name match ≠ faithful port —
-the audit script catches the quality side.
+`it("...")` has a matching Python `def test_*()`. Must show 0 missing before
+committing test changes.

README.md

@@ -2,7 +2,7 @@
 
 Multi-platform async chat SDK for Python. Port of [Vercel Chat](https://github.com/vercel/chat).
 
-> **Status: Alpha (0.0.1a12)** — API may change. Not yet tested in production.
+> **Status: Alpha (0.25.0 — synced to [Vercel Chat 4.25.0](https://github.com/vercel/chat))** — API may change.
 
 ## Why chat-sdk?
 

docs/UPSTREAM_SYNC.md

@@ -2,6 +2,66 @@
 
 How to keep `chat-sdk-python` in sync with the [Vercel Chat TS SDK](https://github.com/vercel/chat).
 
+## Version Mapping
+
+Our version number tracks the upstream Vercel Chat minor version:
+
+| Python version | Upstream version | Meaning |
+|---|---|---|
+| `0.25.0` | `4.25.0` | Synced to upstream 4.25.0 |
+| `0.25.1` | `4.25.0` | Python-only fix on top of 4.25.0 |
+| `0.26.0` | `4.26.0` | Synced to upstream 4.26.0 |
+
+The `UPSTREAM_PARITY` constant in `chat_sdk/__init__.py` provides programmatic access
+to the upstream version this release is synced to.
+
+## How to Sync an Upstream Release
+
+Step-by-step procedure for porting a new upstream release (e.g., `4.26.0`):
+
+```bash
+# 1. Update the TS repo and check what changed
+cd /tmp/vercel-chat && git fetch origin
+git log --oneline chat@4.25.0..chat@4.26.0 -- packages/
+
+# 2. For each commit, read the diff
+git diff chat@4.25.0..chat@4.26.0 -- packages/chat/src/
+git diff chat@4.25.0..chat@4.26.0 -- packages/adapter-slack/src/
+# ... repeat for each changed package
+
+# 3. Create a sync branch
+cd /tmp/chat-sdk-python
+git checkout -b sync/upstream-v4.26.0
+
+# 4. Port each change following the TS → Python Porting Hazards below
+
+# 5. Run full validation
+uv run ruff check src/ tests/ scripts/
+uv run ruff format --check src/ tests/ scripts/
+uv run python scripts/audit_test_quality.py
+uv run python scripts/verify_test_fidelity.py
+uv run pytest tests/ --tb=short -q
+
+# 6. Update version
+#    - pyproject.toml: version = "0.26.0"
+#    - README.md: status line
+#    - __init__.py: UPSTREAM_PARITY = "4.26.0"
+#    - CLAUDE.md: version reference
+#    - CHANGELOG.md: new entry
+
+# 7. PR, merge, publish
+gh pr create --title "sync: upstream v4.26.0"
+```
+
+### What to check for each upstream commit
+
+- [ ] New types or fields → add to `types.py`
+- [ ] New methods on Thread/Channel → add to `thread.py`/`channel.py`
+- [ ] New adapter features → update the adapter + tests
+- [ ] New TS tests → run fidelity script, port missing tests
+- [ ] Changed behavior → verify Python matches with regression tests
+- [ ] Review the porting hazards below for each change
+
 ## How to Diff Upstream Changes
 
 ```bash

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "chat-sdk"
-version = "0.0.1a12"
+version = "0.25.0"
 description = "Multi-platform async chat SDK for Python — port of Vercel Chat"
 readme = "README.md"
 license = {text = "MIT"}

src/chat_sdk/__init__.py

@@ -86,6 +86,21 @@
     select_option,
     text_input,
 )
+from chat_sdk.plan import (
+    AddTaskOptions,
+    CompletePlanOptions,
+    Plan,
+    PlanContent,
+    PlanModel,
+    PlanModelTask,
+    PlanTask,
+    PlanTaskStatus,
+    PostableObjectContext,
+    StartPlanOptions,
+    UpdateTaskInput,
+    is_postable_object,
+    post_postable_object,
+)
 from chat_sdk.shared.base_format_converter import BaseFormatConverter
 from chat_sdk.shared.errors import (
     AdapterError,
@@ -165,11 +180,29 @@
     WellKnownEmoji,
 )
 
+# The upstream Vercel Chat version this release is synced to.
+UPSTREAM_PARITY = "4.25.0"
+
 __all__ = [
+    "UPSTREAM_PARITY",
     # Core classes
     "Chat",
     "ThreadImpl",
     "ChannelImpl",
+    # Plan / PostableObject
+    "Plan",
+    "PlanTask",
+    "PlanTaskStatus",
+    "PlanModel",
+    "PlanModelTask",
+    "PlanContent",
+    "StartPlanOptions",
+    "AddTaskOptions",
+    "UpdateTaskInput",
+    "CompletePlanOptions",
+    "PostableObjectContext",
+    "is_postable_object",
+    "post_postable_object",
     # AI
     "to_ai_messages",
     # Card builders (PascalCase primary — matches source TS SDK)