feat(phase8 #92 D8.5-BE): canonical UIMessage chat history + runtime_kind discriminator

[earayu]

Summary

Phase 8 task #92 (D8.5-BE) — first-cut backend migration for non-agent bot path. Per architect msg=01918929 + Weston msg=df87fe24 + earayu2 msg=f20d5034 hard-cut, scope locked at A+B+C only. The translator extension and legacy-class deletion are explicitly deferred (architect canonical: don't build dead-code for a non-agent live path that doesn't exist in current code; let the future feature task handle that, and #80 owns the deletion).

A. runtime_kind discriminator on agent_message

• ORM column on AgentMessage with values agent_runtime / direct_chat / rag_chat (mutually exclusive enum)
• Server-default agent_runtime so existing rows backfill (no data migration step)
• role keeps speaker semantics (user/assistant/system) independent of runtime kind, per Weston msg=94dac98a
• Alembic migration c8f2d34a51e7 (down_revision=84fac9e3d8c2) — additive; downgrade drops the column

B. ChatService._build_v3_chat_history rewrite

• Returns list[AgentTurnSnapshot] (one snapshot per assistant turn) instead of legacy list[list[ChatMessage]]
• Reuses snapshot_assembler.assemble_parts_from_artifacts (chore: fix quantize failed #90 D8.4d projection) so historical turns expose the same UIMessagePart shape the FE consumes from the live SSE stream — D8 §2 wire/at-rest byte-equal
• error_text for FAILED / CANCELLED turns surfaces an error_summary artifact's message, falling back to turn.error_message (mirrors snapshot endpoint contract from chore: fix quantize failed #90)
• Turn's user query exposed via input_text on the snapshot envelope so user/assistant render from a single object per turn
• Legacy helpers (_extract_artifact_text / _extract_references / _map_reference_item / _artifact_type_value / _coerce_timestamp) retired alongside the legacy shape

C. ChatDetails.history schema

• Type changed to Optional[list[AgentTurnSnapshot]]
• Cycle break: conversation.schemas ↔ agent_runtime.uimessage ↔ agent_runtime.schemas ↔ conversation.schemas resolved via TYPE_CHECKING import + module-level ChatDetails.model_rebuild() hook
• AgentTurnSnapshot gains runtime_kind (default "agent_runtime") and input_text so live + historical share the same envelope shape; TurnService.get_turn_snapshot writes both fields on the live snapshot endpoint

D. Deferred (out of #92 scope)

• Translator extension for chat.text.delta / chat.completed envelope types — non-agent live SSE path doesn't exist; reintroducing it is a feature task
• StoredChatMessagePart / RedisChatMessageHistory deletion — Weston msg=df87fe24 / PM msg=01918929 → owned by [Features] on premise deployment #80 post-soak

Tests

• NEW test_get_chat_returns_canonical_uimessage_history pins the new shape (snapshot per turn with text + source-url + data-citation parts, runtime_kind, input_text, timeline_cursor)
• NEW test_get_chat_history_surfaces_error_text_for_failed_turn pins error_text contract for FAILED turns (artifact-preferred → turn.error_message fallback)
• NEW test_get_chat_history_does_not_expose_legacy_chatmessage_shape regression-guard against revert to list[list[ChatMessage]]
• test_agent_runtime_v3.py import path updated (AgentTurnSnapshot now imported from uimessage directly; back-compat re-export through schemas retired to break cycle)

Per D10 §G hard gate 1 (comprehensive grep sweep) ran across aperag/ + tests/unit_test/ + tests/e2e_http/hurl/ + tests/e2e_http/scripts/. Only web/src/components/chat/chat-messages.tsx reads chat.history in the old shape — that's the explicit hand-off seam for #93 huangheng (per architect msg=6e53a7c4).

Hand-off for #93 huangheng (FE)

Per huangheng's questions in msg=4017bc0c:

1. ChatDetails.history shape: list[AgentTurnSnapshot] (each snapshot has turn_id / chat_id / runtime_kind / role: "assistant" / status / parts: UIMessagePart[] / error_text? / timeline_cursor / input_text / timestamps)
2. getBotChat endpoint: unchanged — GET /api/v2/bots/{bot_id}/chats/{chat_id} still returns ChatDetails
3. Snapshot endpoint reuse: yes — non-agent uses the same AgentTurnSnapshot shape (now with runtime_kind discriminator). The endpoint stays at /api/v2/agent/chats/{cid}/turns/{tid} for now; a non-agent specific endpoint is not needed because the production non-agent live path doesn't exist
4. runtime_kind in FE: surfaced for transparency but FE need not branch on it for [Features] store the celery task result to a backend #93 — historical render uses parts directly
5. Each historical turn has turn_id: yes, from agent_turn table (existing)

Test plan

• pytest tests/unit_test/agent_runtime/ tests/unit_test/chat/ -q → 139 passed
• pytest tests/unit_test --deselect concurrent_control flake -q → 833 passed / 29 skip / 0 fail
• ruff check → clean
• ruff format --check → clean (448 files)
• e2e-http-smoke + e2e-http-provider — pending CI
• FE typed schema regen (yarn api:v2:types) — yarn not available in BE worktree; [Features] store the celery task result to a backend #93 huangheng will regen as part of FE migration
• CR — pending Opus reviewer per RR2 single-Opus-CR

Phase 8 D8.x Phase A + B + #90 + #92 status

Task	Status
#73 D8.1 wire emitter	✅ merged 51137301
#74 D8.2 at-rest storage	✅ merged e290488b
#75 D8.3 tool/citation/consent	✅ merged bd4052d5
#76 D8.4a SDK transport	✅ merged 63a9d522
#77 D8.4b parts renderer	✅ merged f0351662
#78 D8.4c interactive consent UI	✅ merged 3195d18b
#90 D8.4d snapshot canonical parts	✅ merged 3f9303cd
#92 D8.5-BE	this PR
#93 D8.5-FE	huangheng, awaits this PR's first-cut
#80 D8.6 cleanup	parked, post-soak

🤖 Generated with Claude Code