Sync upstream 4.28 + 4.29 (next sync after 4.27 wave lands)

[patrick-chinchill]

Status (updated 2026-05-28)

0.4.27 shipped (release c43ea05 on main, tag v0.4.27). Wave 4.27 → 4.29 now in flight.

• Alpha-bump PR: sync: upstream v4.29.0 (alpha 1) #108 (claude/sync-upstream-4.29)
• Design issues filed for the two biggest items: Design: chat/ai subpath port (vercel/chat#492) #109 (chat/ai subpath, ~7 days), Design: Messenger (Meta) adapter port (vercel/chat#461) #110 (Messenger adapter, ~5-6 days)
• Tracking the rest in the alpha PR's CHANGELOG

Background

Upstream has moved on while the 4.27 sync (PRs #83, #85, #86, #87, #88, #89, #90) was in flight:

• chat@4.27.0 — NEVER got a chat@* tag (only @chat-adapter/shared@4.27.0)
• chat@4.28.0 — NEVER got a chat@* tag
• chat@4.29.0 — released 2026-05-18, now tagged

chat@4.29.0 is the next real upstream tag and the target for this sync.

What's between our 0.4.27 baseline and chat@4.29.0

37 substantive commits in packages/. Already-covered items (no work):

• ✅ fix(telegram): apply MarkdownV2 entity safety trim to streaming chunks vercel/chat#446 Telegram MarkdownV2 streaming-chunk safety trim — already in our 0.4.27 (PR fix(adapters): bug-fix sweep from upstream 4.27.0 (slack/discord/telegram) #89 helpers)
• ✅ feat: make adapter internals protected to enable subclassing vercel/chat#475 private → protected adapter internals — our _underscore convention already provides this; zero __name_mangled internals across all 8 adapters

Sync scope (TODO)

Core (packages/chat)

• chat/ai subpath for AI SDK utilities (feat(chat): add chat/ai subpath for AI SDK utilities vercel/chat#492) — design: Design: chat/ai subpath port (vercel/chat#492) #109
• queue-debounce concurrency strategy (feat(chat): add queue-debounce concurrency strategy vercel/chat#495)
• Transcripts API + per-thread cache rename to threadHistory (feat(chat): add Transcripts API + rename per-thread cache to threadHistory vercel/chat#448) — has chinchill-api blast radius
• callbackUrl on buttons and modals (feat(chat): add callbackUrl to buttons and modals vercel/chat#454)
• message.subject + adapter client access (feat(chat): add message.subject and adapter client access vercel/chat#459)

All adapters

• adapter.client rename → adapter.octokit / adapter.linearClient / adapter.webClient (feat: rename adapter.client to adapter.octokit / adapter.linearClient / adapter.webClient vercel/chat#478)

Slack

• Native markdown_text for outgoing messages (feat(slack): use native markdown_text for outgoing messages vercel/chat#440) — deferred from 0.4.27
• External installation provider for bot token management ([slack] add support for external installation providers for bot token management vercel/chat#467)
• Flip webhook_verifier > signing_secret precedence (fix(slack): prefer webhookVerifier over signingSecret vercel/chat#468) — our 0.4.27 went the opposite direction; upstream has since reversed itself
• Expose direct WebClient via adapter.client (feat(slack): expose direct WebClient access via adapter.client vercel/chat#471, reapplied in #476)

Discord

• Handle interactions in gateway-only mode (fix(discord): handle interactions in gateway-only mode vercel/chat#490) — coordinates with issue Discord adapter: port native Gateway WebSocket support (HTTP-only today) #57 (Discord native Gateway)

Telegram

• Typed attachment uploads (feat(telegram): support typed attachment uploads vercel/chat#485)
• video_note round video messages (fix(adapter-telegram): handle video_note (round video messages) in extractAttachments vercel/chat#457)

Teams

• Migrate to microsoft-teams-apps SDK (issue Migrate Teams adapter to microsoft-teams-apps (official MS Python SDK) #93) — replaces hand-rolled streaming, requires Python 3.12 floor bump

New packages

• Messenger (Meta) adapter ([messenger] add messenger (meta) platform adapter to chat sdk vercel/chat#461) — design: Design: Messenger (Meta) adapter port (vercel/chat#461) #110
• [⏭️] @chat-adapter/web (feat: add @chat-adapter/web — browser chat UI for chat-sdk bots vercel/chat#444) — out of scope, no browser runtime
• @chat-adapter/tests test kit (feat(tests): add @chat-adapter/tests test kit vercel/chat#470) — evaluate vs our existing adapter-test pattern

Open questions

1. Cadence: one wave (4.27 → 4.29) or split (4.27 → 4.28, then 4.28 → 4.29)? Default in PR sync: upstream v4.29.0 (alpha 1) #108: one wave.
2. Python floor bump to 3.12 (required for Teams SDK migration). Confirm chinchill-api compatibility.
3. Discord Gateway scope: ship Gateway support in this wave (issue Discord adapter: port native Gateway WebSocket support (HTTP-only today) #57) or keep #490 isolated?
4. adapter.client rename: deprecation shim for one release, or hard cutover?
5. Plus the chat/ai-specific and Messenger-specific questions in Design: chat/ai subpath port (vercel/chat#492) #109 and Design: Messenger (Meta) adapter port (vercel/chat#461) #110.

Acceptance criteria (carried from original filing)

• UPSTREAM_PARITY = "4.29.0" ✅ (done in sync: upstream v4.29.0 (alpha 1) #108)
• Lint workflow re-pinned to chat@4.29.0
• scripts/fidelity_baseline.json regenerated against 4.29.0
• All headline items above ported or explicitly documented as deferred in docs/UPSTREAM_SYNC.md
• Teams SDK migration (Migrate Teams adapter to microsoft-teams-apps (official MS Python SDK) #93) lands within this sync (or has an explicit deferred-to-0.4.30 row)

References

• Alpha-bump PR: sync: upstream v4.29.0 (alpha 1) #108
• Design issues: Design: chat/ai subpath port (vercel/chat#492) #109 (chat/ai), Design: Messenger (Meta) adapter port (vercel/chat#461) #110 (Messenger)
• Teams SDK migration: Migrate Teams adapter to microsoft-teams-apps (official MS Python SDK) #93
• Discord Gateway: Discord adapter: port native Gateway WebSocket support (HTTP-only today) #57
• 4.27 wave (prior sync): sync: upstream v4.27.0 (alpha 1) #83 (alpha) + fix(adapters): Slack streaming team_id + Teams DM Graph conversation IDs (vercel/chat#330, #403) #85-fix(gchat): use full markdown parser for card text rendering #92, fix(streaming-markdown): list-marker awareness + table chunk-boundary (issue #69) #99, fix(markdown): chat-scoped completeness — escaped chars, task lists, math/escape in _remend #101, fix(slack): use channel= kwarg for files_upload_v2 (closes #102) #103, feat(adapters): log init for gchat + github, include registered adapters in not-found error #104, fix(adapters): accept dict StreamChunks in slack/github/google_chat streams #105 (ports + fixes)