vvzvlad/gitmost
1
0
Fork 0
Code Issues 14 Pull Requests 12 Packages Projects Releases Activity

feat(ai-chat): persistent history as source of truth — step durability + server export (#183) #186

Merged
Ghost merged 4 commits from feat/ai-chat-persistent-history into develop 2026-06-25 12:40:36 +03:00
Conversation 0 Commits 4 Files Changed 23 +2018 -1482
Ghost commented 2026-06-25 06:06:18 +03:00
Copy Link

Closes #183. Отдельный PR (не часть батча #185).

История AI-чата жила в несогласованных парадигмах (стрим в памяти + клиентский экспорт vs БД-как-контекст) — отсюда хрупкий экспорт и потеря ответа ассистента при смерти процесса в середине хода. Делаем БД единственным источником истины.

A. Шаговая durability (сервер)

  • Колонка status в ai_chat_messages (миграция; NULL = legacy = completed). Ассистентская строка теперь создаётся сразу как status:'streaming' и апдейтится на каждом onStepFinish (текст + tool calls + tool RESULTS), затем один раз финализируется в completed/error/aborted на терминальном колбэке. Смерть процесса в середине хода сохраняет все завершённые шаги; sweep на старте (OnModuleInit → sweepStreaming) переводит висящие streaming → aborted. Путь записи больше не зависит от живого сокета.
  • Чистая flushAssistant(steps, inProgressText, status, extra?) строит payload (metadata.parts байт-в-байт как старый билдер) — будущий фоновый воркер сможет звать тот же путь. AiChatMessageRepo: update, sweepStreaming, findAllByChat.
  • consumeStream drain, close-once внешних MCP-клиентов, SSE-heartbeat — сохранены.

B. Серверный экспорт

  • Новый чистый chat-markdown.util.ts рендерит markdown ТОЛЬКО из строк БД (порт клиентского билдера). Благодаря A в экспорт попадает и незавершённый ход (до последнего шага, с пометкой «still generating»). POST /ai-chat/export (owner-gated через assertOwnedChat, workspace-scoped). lang принимает полный locale-таг (en-US/ru-RU) и нормализуется на сервере (normalizeLang).
  • Клиент: handleCopy зовёт эндпоинт; canExport = !!activeChatId. Весь гибрид liveThreadRef/liveStateRef/onLiveContentChange/hasLiveContent (и клиентский chat-markdown util + тест) удалён — сервер теперь авторитетен.

Найденный и исправленный баг (через браузерное тестирование)

Строгий @IsIn(['en','ru']) на lang отклонял реальный i18n.language клиента (en-US) с 400. Юнит-тесты (передавали 'en'/'ru' напрямую) это не ловили — поймал прогон через реальный клиент в браузере. Исправлено: DTO принимает строку, сервер нормализует; добавлен регресс-тест на locale-таги.

Проверки

  • server build + 318 ai-chat unit + 3 integration (update/sweepStreaming с реальным SQL).
  • client tsc + 157 ai-chat unit (тесты удалённого клиентского экспорта сняты).
  • End-to-end в реальном браузере: ход чата персистится в БД ПРЯМО во время стрима (status='streaming'), кнопка Copy экспортирует markdown из БД (видна in-progress строка с пометкой «still generating»), HTTP 200 после фикса локали.

Не мержу.

🤖 Generated with Claude Code

Closes #183. Отдельный PR (не часть батча #185). История AI-чата жила в несогласованных парадигмах (стрим в памяти + клиентский экспорт vs БД-как-контекст) — отсюда хрупкий экспорт и потеря ответа ассистента при смерти процесса в середине хода. Делаем БД единственным источником истины. ## A. Шаговая durability (сервер) - Колонка `status` в `ai_chat_messages` (миграция; NULL = legacy = completed). Ассистентская строка теперь **создаётся сразу** как `status:'streaming'` и **апдейтится на каждом `onStepFinish`** (текст + tool calls + tool RESULTS), затем один раз финализируется в completed/error/aborted на терминальном колбэке. Смерть процесса в середине хода сохраняет все завершённые шаги; sweep на старте (`OnModuleInit` → `sweepStreaming`) переводит висящие `streaming` → `aborted`. Путь записи больше не зависит от живого сокета. - Чистая `flushAssistant(steps, inProgressText, status, extra?)` строит payload (metadata.parts байт-в-байт как старый билдер) — будущий фоновый воркер сможет звать тот же путь. `AiChatMessageRepo`: `update`, `sweepStreaming`, `findAllByChat`. - `consumeStream` drain, close-once внешних MCP-клиентов, SSE-heartbeat — сохранены. ## B. Серверный экспорт - Новый чистый `chat-markdown.util.ts` рендерит markdown ТОЛЬКО из строк БД (порт клиентского билдера). Благодаря A в экспорт попадает и незавершённый ход (до последнего шага, с пометкой «still generating»). `POST /ai-chat/export` (owner-gated через `assertOwnedChat`, workspace-scoped). `lang` принимает полный locale-таг (`en-US`/`ru-RU`) и нормализуется на сервере (`normalizeLang`). - Клиент: `handleCopy` зовёт эндпоинт; `canExport = !!activeChatId`. Весь гибрид `liveThreadRef`/`liveStateRef`/`onLiveContentChange`/`hasLiveContent` (и клиентский chat-markdown util + тест) удалён — сервер теперь авторитетен. ## Найденный и исправленный баг (через браузерное тестирование) Строгий `@IsIn(['en','ru'])` на `lang` отклонял реальный `i18n.language` клиента (`en-US`) с **400**. Юнит-тесты (передавали 'en'/'ru' напрямую) это не ловили — поймал прогон через реальный клиент в браузере. Исправлено: DTO принимает строку, сервер нормализует; добавлен регресс-тест на locale-таги. ## Проверки - server build + **318** ai-chat unit + **3** integration (update/sweepStreaming с реальным SQL). - client tsc + **157** ai-chat unit (тесты удалённого клиентского экспорта сняты). - **End-to-end в реальном браузере**: ход чата персистится в БД ПРЯМО во время стрима (status='streaming'), кнопка Copy экспортирует markdown из БД (видна in-progress строка с пометкой «still generating»), HTTP 200 после фикса локали. Не мержу. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Ghost added 1 commit 2026-06-25 06:06:19 +03:00
feat(ai-chat): persistent history as source of truth — step durability + server export (#183) e7b719bbb8 
The chat lived in inconsistent paradigms (in-memory stream + client export vs.
DB-as-context), which made export flaky and lost the assistant answer if the
process died mid-turn. Make the DB the single source of truth.

A. STEP-GRANULAR DURABILITY (server)
- ai_chat_messages gains a nullable `status` column (migration; NULL = legacy =
  completed). The assistant row is now INSERTED UPFRONT as `status:'streaming'`
  and UPDATEd on every onStepFinish with all finished steps (text + tool calls +
  tool RESULTS), then finalized once to completed/error/aborted on the terminal
  callback. So a process death mid-turn keeps every finished step; a startup
  sweep (OnModuleInit → sweepStreaming) flips any dangling 'streaming' row to
  'aborted'. The write path no longer depends on a live socket.
- Pure exported `flushAssistant(steps, inProgressText, status, extra?)` builds
  the persist payload (metadata.parts byte-identical to the old builder), so a
  future background worker can call the same path. AiChatMessageRepo gains
  `update`, `sweepStreaming`, and `findAllByChat`.
- consumeStream drain, external-MCP client close-once, SSE heartbeat preserved.

B. SERVER-SIDE EXPORT
- New pure `chat-markdown.util.ts` renders Markdown from DB rows ONLY (server
  port of the client builder). Because A persists the in-progress row, the
  export now includes an interrupted turn up to its last finished step (flagged
  "still generating"). `POST /ai-chat/export` (owner-gated via assertOwnedChat,
  workspace-scoped) returns it; `lang` accepts a full client locale tag
  ('en-US'/'ru-RU') and is normalized server-side (normalizeLang) — a strict
  @IsIn(['en','ru']) DTO rejected the real client's i18n.language with a 400,
  caught in real-browser testing.
- Client: handleCopy calls the endpoint; `canExport = !!activeChatId`. The whole
  liveThreadRef/liveStateRef/onLiveContentChange/hasLiveContent hybrid (and the
  client chat-markdown util + test) is removed — the server is now authoritative.

Tests: flushAssistant unit (status shapes + parts parity), chat-markdown.util
unit (incl. legacy NULL-status + interrupted note + ru + normalizeLang locale
tags), controller export wiring + owner-gate, integration update/sweepStreaming.
Verified: server build + 318 ai-chat unit + 3 integration; client tsc + 157
ai-chat unit; and END-TO-END in a real browser — a chat turn persists mid-stream
and the Copy button exports the DB-sourced markdown (showing the in-progress
row), HTTP 200 after the locale fix.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Ghost added 1 commit 2026-06-25 06:14:16 +03:00
fix(ai-chat): guard step-update vs finalize race with WHERE status='streaming' (#183 review) ae6faf3abc 
Review caught a real race: onStepFinish fires `updateStreaming()` fire-and-
forget (not awaited), so the FINAL step's streaming UPDATE and the terminal
`finalizeAssistant` UPDATE run as two concurrent statements on different pool
connections — commit order is not guaranteed. If the late streaming update
lands AFTER finalize, the completed row is clobbered back to status='streaming'
with no usage/finishReason, and the next startup sweep then mis-marks the
finished turn 'aborted'. Green unit/integration tests don't reproduce a
cross-connection race.

Fix: scope the per-step update with `onlyIfStreaming` → SQL `WHERE
status='streaming'`. Once finalize has set a terminal status the late update
matches zero rows and no-ops, regardless of commit order; finalize runs
unguarded so it always wins. A cheap `if (finalized) return` short-circuit
avoids most wasted queries, but the SQL guard is the authoritative fix (the
flag can be set after a query is already in flight).

Integration test: finalize to 'completed', then a late onlyIfStreaming update
is a no-op — status/content/usage preserved.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Ghost added 1 commit 2026-06-25 11:53:39 +03:00
refactor(review): address PR #186 review (#183 — recency sweep, #174 export, tests, cleanups) ea61c96a7c 
15-point review of the persistent-history PR. Architecture decisions: crash
recovery = recency threshold; tool-label duplication = leave as-is.

Must-fix:
1. Boot-sweep bounded by recency. sweepStreaming now also requires
   `updatedAt < now() - SWEEP_STREAMING_STALE_MS` (10 min), so a fresh replica's
   startup sweep can't abort a turn another replica is actively streaming
   (multi-instance deploy). Int-spec: a FRESH 'streaming' row is NOT swept, a
   STALE one IS.
2. Restore export during the FIRST streaming turn of a new chat (#174). The
   server chatId is now adopted EARLY (in-place, on the start-chunk metadata) via
   a new `onServerChatId` callback wired through use-chat-session → chat-thread,
   so `activeChatId` is set at turn start and the Copy button is live mid-first-
   turn (canExport = !!activeChatId). Hook tests for early/in-place/no-op adopt.
3. Cover finalizeAssistant's fallback-insert branch: extracted pure
   `planFinalizeAssistant(assistantId)` (update when id present, insert when the
   upfront insert failed) + a dispatch harness test for both arms.

Tests: onModuleInit lifecycle spec (sweep called; throw → resolves + warns);
int-spec updatedAt assertion → toBeGreaterThan.

Cleanups: cap findAllByChat at 5000 rows; upfront-insert-failure log carries
chatId+workspaceId; removed the now-dead buildPartialAssistantRecord (only the
spec consumed it; shapes still pinned by the flushAssistant suite); controller
passes `lang: dto.lang` (normalizeLang handles undefined); dropped a no-op
`?? undefined` in errorOf; documented the content-column semantics change
(concatenated step text, UI renders from metadata.parts); CHANGELOG [Unreleased]
entry (#183, #174); reworded the stale LABELS parity comment.

Verified: server build + 323 ai-chat unit + 5 integration; client tsc + 160
ai-chat unit; prettier clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Ghost added 1 commit 2026-06-25 12:31:00 +03:00
refactor(review): address PR #186 re-review (approve-with-comments) aa7a115f66 
Approve-with-comments re-review; no blockers. All 7 actionable points (8 is a
forward-looking architecture note — recommendation A, keep as-is):

1. chat-markdown.util spec: restore parity coverage of the removed client spec —
   tool error state (+ errorText), unknown-tool fallback (`Ran tool <name>` en /
   `Выполнил инструмент <name>` ru), and the circular-output stringify catch.
2. findAllByChat row cap is now testable (injectable limit) + an int-spec proves
   truncation on a modest volume.
3. Stability: the per-step durability updates are SERIALIZED via a promise chain
   (stepUpdateChain) so they commit in step order — onlyIfStreaming already
   closed the finalize race, this closes inter-step ordering.
4. findAllByChat keeps the NEWEST messages on truncation (order DESC + reverse,
   like findRecent) and logs a warning with chatId, instead of silently dropping
   the newest tail.
5. The LABELS parity comment already references the real path (tool-parts.tsx /
   toolLabelKey) — confirmed accurate.
6. Removed the redundant 'off-by-one boundary' test (strict subset of the two
   adjacent prepareAgentStep cases).
7. Extracted the terminal-finalize dispatch into a shared `applyFinalize`, used
   by BOTH the service's finalizeAssistant and its test — the test now exercises
   the real path, not a copy, so a production drift fails it.

Verified: server build + 325 ai-chat unit + 6 integration; prettier clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Ghost merged commit de115ade1e into develop 2026-06-25 12:40:36 +03:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
bug
Something isn't working
 documentation
Improvements or additions to documentation
 duplicate
This issue or pull request already exists
 enhancement
New feature or request
 epic
Large multi-phase effort spanning many changes
 feature
New functionality request
 good first issue
Good for newcomers
 help wanted
Extra attention is needed
 idea
Idea / proposal for discussion
 invalid
This doesn't seem right
 needs-human
эскалация: нужно решение человека
 question
Further information is requested
 refactor
Code cleanup / refactoring
 review/approved
в последнем ревью нет открытых blocking-находок
 review/changes-requested
последнее ревью оставило открытые blocking-находки
 review/needs
head не ревьюился (head != reviewed_head)
 security
Security / hardening issue
 status/blocked
ждёт зависимость blocked_by
 status/done
закрыто и проверено
 status/in-progress
в активной работе (мягкая заявка)
 status/ready
специфицировано, не заблокировано, ждёт исполнителя
 test
Test coverage / test infrastructure
 wontfix
This will not be worked on
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
agent_coder agent_reviewer vvzvlad
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: vvzvlad/gitmost#186
Delete Branch "feat/ai-chat-persistent-history"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?