feat(phase8 #90 D8.4d): snapshot endpoint returns canonical UIMessage parts

[earayu]

Summary

Phase 8 task #90 (D8.4d) — replaces the agent runtime turn snapshot endpoint's legacy {turn, timeline, artifacts} envelope with the canonical UIMessage-aligned AgentTurnSnapshot shape. The FE renderer (#76 / #77 / #78) now consumes the same UIMessagePart discriminated union from both the live SSE stream and the at-rest reload path, per D8 §2 wire / at-rest byte-equal canonical (architect msg=711f8c2f canonical lock + PM scope msg=383c2e2b / msg=247f4d8e).

What changed

Backend

• NEW aperag/domains/agent_runtime/snapshot_assembler.py — projects legacy AgentArtifact rows into UIMessagePart[] (answer → TextPart, reference_bundle → SourceUrlPart + DataCitationPart, error_summary → error_text). Mirrors the FE-side snapshot-fallback.ts adapter that feat: support default collections #77 huangheng landed as a transitional bridge so deletion was mechanical from both sides.
• AgentTurnSnapshot (now defined in uimessage.py alongside the rest of the UIMessage family; re-exported from schemas.py for back-compat) flips to {schema_version, turn_id, chat_id, role, status, parts, error_text?, timeline_cursor, ...timestamps}.
• TurnService.get_turn_snapshot() rewritten:
  1. Forward-compat — try UIMessageStore.read(turn_id) first (D8.6 will populate agent_message.parts directly via the wire emitter; today the store is optional and reads return None).
  2. Fallback — assemble_parts_from_artifacts projects legacy artifacts.
  3. error_text — extract_error_text pulls the error_summary payload (or summary), falling back to runtime_state.error_message.
• The 3 ownership-only callers of get_turn_snapshot (cancel / consent / elicit endpoints) are unaffected — they only use the call to trigger ResourceNotFoundException, never read the body.

Frontend (deletes the #77 transitional adapter)

• web/src/features/agent-runtime/api.ts — AgentTurnSnapshotEnvelope flips to the new flat shape; legacy {turn, timeline, artifacts} types gone.
• web/src/components/chat/chat-messages.tsx — seedFromSnapshot synthesizes a minimal AgentTurnEnvelope from the new flat snapshot for the live-turn store; reload rendering reads baselineSnapshot.parts and baselineSnapshot.error_text directly with no client-side synthesis.
• web/src/features/agent-runtime/snapshot-fallback.ts — synthesizePartsFromSnapshot and extractErrorTextFromSnapshot are removed (their TODO(#90) trigger has fired). mapBackendTurnStatus / isTerminalBackendStatus are kept (status mapping stays useful).
• web/src/features/agent-runtime/index.ts — dropped exports removed from the barrel.

Boundary discipline

• In-scope (per PM scope lock):
  • Snapshot endpoint shape change
  • Legacy {turn, timeline, artifacts} keys retired
  • OpenAPI contract preserved (schema name unchanged; fields differ)
  • Minimal regression tests
  • FE consumption updated to new shape (huangheng's transitional snapshot-fallback.ts adapters retired)
• Out-of-scope (per architect / PM):
  • Wire emitter / live SSE ([Features] integrate Slack bot as a frontend of kubechat #73 territory, untouched)
  • At-rest UIMessage storage main design ([Features] support preview and download documents #74 territory, untouched)
  • Tool lifecycle / consent / elicitation ([Features] integrate YuQue as a data source #75 territory, untouched)
  • Renderer shell (feat: support default collections #77 territory, untouched)
  • Consent/elicitation UI body (chore: fix embedding timeout and scale the embedding workers #78 territory, untouched)
  • legacy-snapshot-shim.ts was already deleted by feat: support default collections #77

Tests

• NEW tests/unit_test/agent_runtime/test_snapshot_assembler.py — 8 contract tests pinning the artifact → UIMessagePart projection (answer text, reference-bundle fan-out with and without uri, ordering, unknown-artifact skip, error-text extraction with payload-preferred / summary fallback / none-without-error_summary).
• tests/unit_test/agent_runtime/test_agent_runtime_v3.py snapshot tests rewritten for the new shape:
  • test_turn_snapshot_returns_canonical_uimessage_parts_for_completed_turn
  • test_turn_snapshot_surfaces_error_text_for_failed_turn
  • test_turn_snapshot_does_not_expose_legacy_keys (regression-guard: {turn, timeline, artifacts} must not reappear)
  • test_turn_snapshot_user_activity_inference_runs_via_event_service pins the empty-timeline guarantee.
• tests/e2e_http/hurl/full/15_agent_runtime_v3.hurl snapshot assertions migrated to the new shape (turn_id, chat_id, role, status, parts at top level; legacy keys gone).
• tests/unit_test/agent_runtime/test_agent_runtime_openapi_contract.py — continues to pass (schema name unchanged).

Test plan

• pytest tests/unit_test/agent_runtime/ -q → 134 passed
• pytest tests/unit_test --deselect concurrent_control flake -q → 831 passed / 29 skipped / 0 failed
• ruff check → clean
• ruff format --check → clean (446 files already formatted)
• e2e-http-smoke + e2e-http-provider — pending CI (per merge-gate rule)
• FE typed schema (web/src/api-v2/schema.d.ts) regen via yarn api:v2:types — yarn is not available in this worktree; CI / a follow-up FE-touching PR will resync if a drift is observed.
• CR — pending Weston (per architect msg=711f8c2f middle-term lane lock)

Phase 8 Phase B / D8.4d status

Lane	Owner	Status
#76 D8.4a transport	huangheng	merged 63a9d522
#77 D8.4b renderer	huangheng	merged f0351662
#78 D8.4c consent/elicit body	chenyexuan	in_review (chained on #77)
#90 D8.4d snapshot endpoint	Bryce	this PR

Per architect canonical: this PR retires snapshot-fallback.ts (the FE transitional adapter) end-to-end, keeping the remaining mapBackendTurnStatus helper. After this lands, the only remaining D8.x backend cleanup is D8.6 / #80 (drop legacy agent_artifact / agent_timeline_event tables once the wire emitter starts populating agent_message.parts directly).

🤖 Generated with Claude Code