feat(chat-kit): chat protocol v1 package + greenfield chat design docs

Merged
SA
3mo ago
+2233-103

What

First PR of the greenfield chat rebuild (desktop + mobile). Two things:

packages/chat — the client-safe foundation, ./protocol + ./core entries:

  • zod schemas for the wire contract: seven-kind item vocabulary (user_message, agent_message, reasoning, tool_call, plan, approval_request, notice), epoch-qualified cursors, durable/delta/reset envelopes, commandId-keyed command inputs
  • one pure reducer shared by live streaming and history replay (full-snapshot upserts by item id)
  • derived-timeline projections (turn grouping, settled-tool-run collapsing, pending approvals)
  • streaming-markdown block splitter + open-fence detection (highlighter gating), outbox (clientId-echo reconciliation), frame coalescer
  • 18 tests asserting the convergence invariants: shuffled/duplicated/dropped delivery converges, replay == live, snapshots supersede deltas, cross-epoch events are rejected, settled markdown blocks stay byte-identical while streaming

plans/ — the design record:

  • chat-ui-greenfield-research.md — competitor/ecosystem synthesis (Codex app-server, T3 Code, Conductor, ACP v2, assistant-ui, measured perf work across LibreChat/Cherry Studio/etc.)
  • chat-protocol-v1.md — the wire spec and its ten invariants
  • chat-harness-adapters.md — Claude (Agent SDK direct) + Codex (app-server JSON-RPC) adapters, placement in host-service with an extraction seam
  • chat-ship-plan.md — workstreams, milestones, and the new-pane-replaces-old-pane rollout
  • 20260804-chat-protocol-decisions.md — the ratified decision log

Why

Three current chat stacks share almost nothing, hold no durable message history anywhere, and both UI kits are duplicated. This rebuild follows the architecture Codex, T3 Code, opencode, and Zed independently converged on: one item vocabulary, a durable event spine with ephemeral deltas, one reducer for live + replay, headless core + thin per-platform renderers.

Supersedes plans/v2-chat-greenfield-architecture.md (kept mastracode + AI SDK UIMessage; both overturned with rationale in the research doc).

Next

M0 spikes (record real Claude/Codex fixture streams, relay WS soak, RN markdown benchmark) + Workstream B: host journal driven by a scripted fake harness.

https://claude.ai/code/session_01XRFCEPsfmJHu2SenDKYJ2h

Summary by cubic

Introduces Chat Protocol v1 in @superset/chat (protocol + headless core), adds a durable session runtime in @superset/chat-runtime, and moves the existing stack to @superset/chat-legacy with desktop imports rewired to keep behavior unchanged.

  • New Features

    • packages/chat exports ./protocol and ./core: zod-validated item/envelope/command types, a pure reducer shared by live and replay, timeline derivation, streaming markdown splitter, outbox with retry/echo reconciliation, and frame coalescing; tests cover convergence invariants.
    • packages/chat-runtime: standalone session runtime with its own SQLite journal (WAL), epoch minting/reset signaling, readSince/readPage, a session read model, a HarnessAdapter interface with a scripted fake harness, and a live layer (LiveSession, SubscriptionHub, replay-then-live, delta filtering, coalescing); command parsing with commandId dedupe; tests verify replay==live and reconnect equality.
    • Design docs: protocol spec, adapter plan (Claude/Codex), ship plan, research synthesis, and decision log.

  • Migration

    • The mastra-era implementation is now @superset/chat-legacy; desktop and TRPC imports are updated to use it. @superset/chat is the new protocol/core going forward. AGENTS.md notes that slash-command discovery remains in @superset/chat-legacy.

Summary by CodeRabbit

  • New Features

    • Added Anthropic and OpenAI API key and OAuth authentication with persistence, expiration handling, and fallback support.
    • Added slash-command discovery, aliases, argument parsing, built-in commands, file search, and MCP tools.
    • Added streaming chat foundations with Markdown rendering, approvals, queued messages, recovery, and timeline organization.
    • Added durable sessions with replay, reconnection, history, and continuation support.

  • Bug Fixes

    • Prevented duplicate in-progress assistant messages while preserving completed conversation history.

  • Documentation

    • Documented Chat Protocol v1 decisions, UI research, adapter design, and delivery plans.

Update: the old mastra-era packages/chat was renamed packages/chat-legacy (mechanical rewrite of its 44 import sites); the new package owns the canonical @superset/chat name.