@ykurilov/agent-chat-flows 0.0.0-stage → 0.55.0

package/CHANGELOG.md

@@ -0,0 +1,252 @@
+# @ykurilov/agent-chat-flows
+
+## 0.55.0
+
+### Minor Changes
+
+- 7b5ed35: Сценарии: подписи событий приложения — `catalog.events` принимает `{ name, label }`; доска, прогон, карточка условия и
+  `describeCondition` с каталогом показывают подпись.
+- 98e1e86: Сценарии: утреннее сообщение перезапускает ряд касаний — молчун каждый день получает утреннее и ряд заново, до потолка
+  дня. Смена поведения для сценариев с утренним и `afterSilence`.
+- b17e389: Сценарии: таймер «наступил день N программы» (`{ type: "timer", from: "program_day", day }`) — выход в начале дня N
+  по нумерации `readRun().day`, без хода приложения. Дополнение к формату v2; `checkFlow` проверяет день против
+  `lengthDays`; на доске «Длится» → «до дня программы», подпись «с дня N».
+  Вошёл в ноду уже в день N или позже — выход в том же ходе, один ответ из новой ноды; так же `since_start`, чей срок
+  прошёл к входу.
+- f1151a6: Сценарии: свои касания ноды на N дней (`nudges.days`) — потом утреннее и общий ряд сценария с начала. Доска:
+  «Свои касания действуют», подпись на карточке.
+
+### Patch Changes
+
+- Updated dependencies [51f7b38]
+- Updated dependencies [cdc7dd7]
+  - @ykurilov/agent-chat-core@0.55.0
+  - @ykurilov/agent-chat-react@0.55.0
+
+## 0.54.0
+
+### Minor Changes
+
+- bc3cef1: Доска сценария: больше места графу. Узкая шапка (`header="compact"`), легенда «Условий выхода» по умолчанию свёрнута в кнопку
+  (`legend`), панель «Сценарий» сворачивается (`inspector`), мини-карта сворачивается (`minimap`), редактор разворачивается на
+  весь экран (`fullscreen`). Свёрнутое запоминается в localStorage (`storageKey`). Договор скина: необязательные `compact` и
+  `fullscreen` у шапки, `compact` у рамки, часть `FlowBoardToggle`.
+
+### Patch Changes
+
+- Updated dependencies [c8fb0dd]
+- Updated dependencies [73d3aaa]
+- Updated dependencies [fa90219]
+  - @ykurilov/agent-chat-react@0.54.0
+  - @ykurilov/agent-chat-core@0.54.0
+
+## 0.53.0
+
+### Minor Changes
+
+- b6a7786: Сценарии: конец разговора без сбоев, «не сейчас», пояс по умолчанию, реплика сотрудника, тихое утро, касания с
+  карточками; расход по списку чатов.
+  
+  - Конец разговора («срок вышел», «не завершил», прощание) больше не зависит от того, начался ли ход касания. Касания
+    сценария не режет потолок ядра «5 ходов сервера подряд»; у `deliverNotices` — свой потолок `maxServerTurnsInRow`
+    (число или `false`, по умолчанию 5, `MAX_SERVER_TURNS_IN_ROW`).
+  - Мягкий потолок сценария: 50 ходов сервера подряд без человека (`timers.maxServerTurnsInRow`), дальше касания ждут
+    его сообщения, конец разговора — в свой срок. Срок без причин писать не повторяется каждый час.
+  - `canWriteNow` → `false` — «не сейчас»: касание через час; `"never"` — молчать до сообщения человека; `{ retryAt: Date }`
+    — в свой момент (негодная дата — как `false`, прошлая — через минуту). Сроки конца разговора не снимаются.
+  - Человек писал до начала дня меньше 3 часов назад (`skipMorningIfHumanWithinMin`) — касания в начале дня ждут, не только
+    утреннее. Переход ноды по сроку и ответ на ночные сообщения не ждут.
+  - Сообщения после жёсткой рамки дня ставят срок на утро сами: ответ на накопленное приходит в `dayStart` при любых
+    касаниях. Их время — в данных чата (`flowHeldHuman`); для правила 3 часов, «не завершил» и перехода «человек молчит»
+    они — сообщения человека.
+  - `attach.deliver` получает `parts` — все части ответа для человека (карточка ролика, картинка, файл, виджет), `text`
+    прежний; `deliverNotices({ awaitAnswer }).answer.parts`; `deliverableParts` из ядра.
+  - `storage.sumUsageByChat({ chatIds, ownerId?, source?, since? })` — расход по списку чатов одним запросом (память,
+    SQLite, PostgreSQL; общие тесты хранилищ).
+  - `createAgentFlow({ defaultTimeZone })` — пояс, пока пояс человека неизвестен. Порядок: человек → страница →
+    `defaultTimeZone` → пояс службы → сервер. `prepareTurn` получает `pageTimeZone` — пояс, присланный страницей.
+  - `service.appendStaffMessage({ ownerId, chatId, text, staffName?, wakeAgent? })` — реплика живого сотрудника: модель
+    видит её словами сотрудника, `person_link_view` словами человека её не считает, проверки ответа агента её текст знают,
+    ход сама не начинает.
+    `flow.noteStaffReply` пишет тем же путём и принимает `staffName`. Экран: необязательный `StaffMessage` скина (договор 25),
+    без него — ответ агента с подписью `labels.notices.staffSaid`.
+  - `flow.tick()` в публичном типе, `factId` из пакета, перемотка до утра у чата, закреплённого через `adopt` без хода.
+  
+  Как обновить приложение: снимите `it.fails` у теста «молчун все три дня»; ответ эксперта кладите
+  `appendStaffMessage` / `noteStaffReply` вместо сообщения собеседника и уберите обёртку `withoutNonPersonWords`; по желанию
+  `defaultTimeZone` и `StaffMessage` в своём скине; снимите `it.fails` у теста «касание, отложенное ночью до утра»;
+  доставляйте `message.parts` в своей доставке касаний; расход по чатам — `sumUsageByChat`.
+
+### Patch Changes
+
+- Updated dependencies [b6a7786]
+  - @ykurilov/agent-chat-core@0.53.0
+  - @ykurilov/agent-chat-react@0.53.0
+
+## 0.52.0
+
+### Minor Changes
+
+- d9b2ea5: Редактор сценариев (`FlowEditor`) для кабинета эксперта: три мелочи.
+  
+  - `readOnly` — доска только для просмотра, пока сценарий правит внешний агент. Нельзя двигать, соединять и удалять узлы,
+    править панели, сохранять, загружать JSON и переводить чаты. Открывать узлы, проверять граф, прогонять и смотреть JSON
+    можно. В шапке плашка «Только просмотр» (`labels.header.readOnly`).
+  - `onSave` может вернуть `{ ok: false, issues?: [{ path, message }] }`: отказ без исключения. Шапка пишет «Не
+    сохранено», `issues` встают у нод и выходов и видны в «Проверить граф». Ничего (`void`) и `{ ok: true }` — успех, как
+    раньше. Исключение из `onSave` — такой же отказ, без необработанной ошибки в консоли.
+  - `className` и `style` у `FlowEditor` идут на корень. Корень по умолчанию занимает высоту родителя, но не меньше 60%
+    экрана (не меньше 420 px), на телефоне — экрана целиком (не меньше 640 px): холст не схлопывается.
+  
+  Как обновить приложение: вместо обёртки «inert» на время правок агента передайте `readOnly`; из `onSave` возвращайте
+  `{ ok: false, issues }` при отказе сервера; ручную высоту у родителя редактора можно убрать. Договор скина редактора: все
+  новые поля необязательные (`saveFailed`, `readOnly` у шапки, `readOnly` у окна JSON, `className` и `style` у раскладки),
+  свой скин без них работает.
+
+### Patch Changes
+
+- @ykurilov/agent-chat-core@0.52.0
+  - @ykurilov/agent-chat-react@0.52.0
+
+## 0.51.0
+
+### Minor Changes
+
+- 41b1726: Проверка ответа: **тексты приложения.** В `replyChecks` появилось `knownTexts: ({ ownerId, chatId }) => string[] | Promise<string[]>` — первое сообщение, прощание, названия роликов: слова и ссылки оттуда больше не вырезаются и не считаются чужими. Если `replyChecks` передан в `flow.withChat(…)`, сценарий сам добавляет свои тексты (общая часть, ноды, первые сообщения, прощание, рамка дня, попутные задачи). **Проверка текста вне хода:** `service.checkReply({ ownerId, chatId, text })` → `{ text, notes }` — те же проверки и тот же набор «виденного», что у хода. **Исправление:** служебные сообщения приложения (`app`, «напиши первым») и реплики сотрудника больше не делают ссылку законной — «виденное от человека» берётся только из сообщений человека (итоги фоновых задач остаются виденными). Если агент должен повторять ссылки из своих служебных сообщений, назовите их в `knownTexts`. Подробно — `docs/reply-check.md`.
+
+### Patch Changes
+
+- cd55c82: Проверка сценария больше не ругается на ноду, в которую ведёт только «срок вышел» (`schedule.deadlineState`): она считается достижимой.
+- Updated dependencies [41b1726]
+  - @ykurilov/agent-chat-core@0.51.0
+  - @ykurilov/agent-chat-react@0.51.0
+
+## 0.50.0
+
+### Minor Changes
+
+- 68b0629: Свободные факты о человеке в карточке клиента: `createAgentFlow({ clientFacts: true })`. Агент пишет факт
+  `flow_note { fact }`, `client_card` показывает и стирает, блок `flow:client` несёт список «Факты о человеке», «забудь всё»
+  стирает и поля, и факты. Свои таблицы приложения — необязательное `clientCard.facts: { read, add, forget }`; нет — факты
+  лежат в таблице модуля записями `fact:<id>`. Правило в инструкции делит факты (карточка) и правила общения (долгая память
+  SDK). `flow.readClientCard` отдаёт факты записями `fact:<id>`, `useClientCard` — опция `factName`. Без `clientFacts` всё как
+  в 0.49. Просмотр ссылки (`person_link_view`): «не открылась — сказать один раз» и расход в журнал описаны в
+  `docs/flows.md` и README web-tools, закреплены тестами.
+- 25aaf22: Перенос идущих чатов и конец разговора снаружи. Сценарий без новых полей ведёт себя как в 0.49. Подробно —
+  `docs/flows.md` и раздел 0.50.0 в `CHANGES.md`.
+  
+  - `flow.adopt({ ownerId, chatId, flowId, versionId, flow, stateId, startedAt, enteredAt, lastHumanAt, lastAgentAt, nudgeStep, today, timeZone })`
+    закрепляет идущий чат сразу, без хода, и ставит срок следующего касания. `today: { firstMessages, humanMessages, dayClosed }`
+    продолжает дневной потолок и рамки дня. Те же поля принимает `loadFlow`. Перенос переживает перезапуск.
+  - `flow.end({ ownerId, chatId, reason, outcome })` — конец разговора со своей причиной (`"switched"`): `onFinish`
+    (`reason`, `outcome`), сроки сняты, дальше — как настроено `afterEnd`. `FlowEndReason` принимает любую строку.
+  - `agent.stepContext` в ходе «пишет первым» получает `firstReasons` — все причины хода; тип `FlowStepContextInput`.
+  - `nudges` в корне сценария — касания без «Дней и времени». Порядок: своё у ноды → `"off"` → `schedule.nudges` →
+    `nudges` сценария. Новая находка проверки `nudges_shadowed`.
+  - Документация: ночью агент отвечает человеку, тихие часы — только для сообщений первым; `admit` → `hold` бывает
+    только после жёсткой рамки дня.
+  
+  ### Как обновить приложение
+  
+  1. Поднимите все пакеты `@ykurilov/agent-chat-*` до этой версии вместе. Миграций нет.
+  2. Ничего больше не нужно, если вы не используете новое.
+  3. Переносите идущие чаты из своей системы — зовите `flow.adopt` для каждого чата после `createChat`, а не ждите
+     `loadFlow` на первом ходе: молчащий чат иначе не получит касаний.
+  4. Если в коде есть исчерпывающая проверка причины конца (`switch (end.reason)` с `never` в `default`), добавьте
+     ветку для своих причин: `FlowEndReason` теперь принимает любую строку.
+  5. Своё хранилище сценариев (`FlowStore`) менять не нужно: новые поля переноса лежат в той же JSON-колонке `placement`.
+
+### Patch Changes
+
+- @ykurilov/agent-chat-core@0.50.0
+  - @ykurilov/agent-chat-react@0.50.0
+
+## 0.49.0
+
+### Minor Changes
+
+- 084cef7: **Ломает приложения (типы и своё хранилище сценариев):** у типа поля сценария `FlowFieldType` появилось значение `"boolean"`, у источника
+  расхода `UsageSource` — `"first_message"`, у `SteerResult.status` — `"held"`. Исчерпывающий `switch` по ним перестанет
+  собираться. Своё хранилище сценариев (`FlowStore`) должно реализовать новый `renewLease()` и третий аргумент `setDue`.
+  
+  Сценарии для приложений: программа по дням (ночь, касания, рамки дня, «срок вышел»), своя служба чата и доставка с
+  исходами, пауза сотрудника, конец разговора с итогом, карточка и пояс человека в базе приложения, попутные задачи.
+  Проверка готового ответа: «чужие слова» и «выдуманные ссылки». Подробно — `docs/flows.md`, `docs/reply-check.md`,
+  раздел 0.49.0 в `CHANGES.md`.
+  
+  - **flows**: формат сценария версии 2 (`schedule`, `nudges`, таймер `state_days`, поле `boolean`, `sideTasks`,
+    `afterEnd`; версия 1 читается сама); `attach({ portFor, deliver })`, `admit`, `pause`/`resume`/`noteStaffReply`,
+    `reportDelivery`, `onFinish`, `clientCard`, `people`, `settled`, `now`; причина перехода `reason`; перенос чата
+    через `loadFlow` (`stateId`, `startedAt`, `enteredAt`); заголовки судьи `judge.openrouter.headers`; встроенная задача
+    «узнать город»; `checkFlow(flow, catalog, { checks })` и `FlowAppChecks` из `/format`; в редакторе панели дней,
+    касаний, рамок и попутных задач, `catalog.fields`, кнопка «К началу следующего дня» (`advanceToNextDay`). Новые
+    таблицы `flow_people`, `flow_side_tasks` и колонки `flow_chats` создаются сами.
+  - **core**: `replyChecks` (список или `{ checks, web: "replace" | "hold" }`), `now`, `markUndelivered`, ответы
+    `beforeTurn` `{ hold: true }` и `{ reply: { text } }`, `deliverNotices({ timeZone, awaitAnswer, usageSource })`,
+    источник расхода `first_message`.
+  - **flows, надёжность**: обход таймеров до 5 ходов одновременно; копия продлевает аренду чата перед ходом и во время
+    него. В `FlowStore` новые `renewLease()` и `setDue(…, { unlessDelivery })`. Недоставленное касание (`failed`,
+    `window_closed`) не засчитывается — тот же шаг через свой срок от отказа; в `FlowRun` новое поле `touch`. «Окно
+    закрыто» снимает любое сообщение человека; «не завершил» считает тишину и от конца паузы сотрудника; пока ждёт
+    повтор доставки, срок не затирается и новых ходов нет.
+  - **server**: `createChatServer` передаёт службе `replyChecks` и `now`.
+  - **messengers**: `onAnswerDelivery` — исход доставки каждого ответа; закрытое окно ВК (950) —
+    `MessengerWindowClosedError` и исход `window_closed`; с `replyChecks` уходит только проверенный текст.
+  - **web-tools**: `createPersonLinkTool` — инструмент `person_link_view`, агент смотрит ссылку, которую прислал человек
+    (адрес из почты ссылкой не считается).
+  - **reply-check** (новый пакет): `foreignWords` и `unknownLinks`; ответ из одной выдуманной ссылки заменяется запасной
+    фразой `labels.linkOnlyReply` (`russianReplyCheckLabels`, `englishReplyCheckLabels`, `ReplyCheckLabels`).
+  - **react**: договор скина версии 24 — необязательное `undelivered` у ответа агента и надпись `answerUndelivered`
+    («Не доставлено»). Скин версии 23 работает без правок.
+  
+  ### Как обновить приложение
+  
+  1. Поднимите все пакеты `@ykurilov/agent-chat-*` до этой версии вместе.
+  2. Найдите в коде приложения исчерпывающие `switch` и словари по этим типам и добавьте ветки:
+     - по `FlowFieldType` (поля карточки сценария) — `"boolean"`, «да/нет», значения `true`/`false`;
+     - по `UsageSource` (отчёты расходов) — `"first_message"`, «агент написал первым»;
+     - по `SteerResult.status` — `"held"`, «сообщение записано, хода нет».
+  3. Своё хранилище сценариев (свой `FlowStore`) — добавьте `renewLease({ chatId, owner, now, leaseMs }): Promise<boolean>`
+     (продлить аренду до `now + leaseMs`; `false` — чат уже не ваш) и третий аргумент `setDue(chatId, due, { unlessDelivery })`
+     (при `unlessDelivery` не писать срок, пока чат ждёт повтора доставки). Готовые хранилища SDK это уже умеют.
+  4. Сценарии сохраняются версией 2, а 0.48 её не откроет. Перед откатом на 0.48 держите копии сценариев версии 1.
+  5. Новое по желанию: каналы SDK и сценарий — `createMessengers({ onAnswerDelivery: (report) => flow.reportDelivery(report) })`;
+     проверка ответа — `pnpm add @ykurilov/agent-chat-reply-check` и `replyChecks` в `createChatServer`.
+  6. Проверка: `pnpm typecheck` проходит, чат отвечает, сценарий версии 1 открывается в редакторе.
+
+### Patch Changes
+
+- Updated dependencies [084cef7]
+  - @ykurilov/agent-chat-core@0.49.0
+  - @ykurilov/agent-chat-react@0.49.0
+
+## 0.48.0
+
+### Minor Changes
+
+- fa10d5a: Сценарии поведения агента: разговор идёт по шагам с условиями выхода, судьёй, таймерами «написать первым» и карточкой
+  клиента, плюс редактор сценария с тестовым чатом. Подробно — `docs/flows.md`.
+  
+  - **flows** (новый пакет): `createAgentFlow`, формат и проверка сценария, судья decision-1 с запасной моделью, таймеры,
+    карточка клиента, перевод чатов на новую версию, хранилища SQLite и PostgreSQL, `FlowEditor`, `FlowTestChat`, `ClientCardPanel`.
+  - **core**: новые точки для расширений — `agent.prepareTurn` (контекст хода с `resumed`, `audience`, `staff?`),
+    служебное сообщение `app`, готовый ответ `deliverNotices({ reply })`, `askModel` и `recordUsage`, источник расхода
+    `judge`, `ChatService.assertWithinLimit(ownerId, chatId)`; `chatInstructions(chat, turn?)` — второй аргумент с
+    `audience` (при сжатии истории его нет).
+  - **server**: `chatInstructions` в настройках принимает тот же второй аргумент `turn`.
+  - **messengers**: ответ сервера без модели (точный текст по таймеру сценария) теперь доходит до мессенджера.
+  - **skin-tandem**: новые входы `/flows` (`tandemFlowEditorSkin`) и `/client-card` (`tandemClientCardSkin`).
+  
+  ### Как обновить приложение
+  
+  Сценарии не нужны — обновление ничего не требует. Нужны — шаги в разделе «Как обновить приложение» в `CHANGES.md`:
+  `pnpm add @ykurilov/agent-chat-flows`, `createAgentFlow` + `flow.withChat(…)`, `flow.attach(service)`, `flow.start()`,
+  `OPENROUTER_API_KEY` на сервере. Тестовому чату нужен `readRun(chatId)` в `FlowTestChatConnection`; его адреса
+  закройте правами редактора. `firstMessages: false` теперь значит «без тихих часов и потолка», запрет —
+  `canWriteNow: () => false`. Проверка: `pnpm typecheck`, новый чат отвечает по первому состоянию сценария.
+
+### Patch Changes
+
+- Updated dependencies [fa10d5a]
+  - @ykurilov/agent-chat-core@0.48.0
+  - @ykurilov/agent-chat-react@0.48.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yury Kurilov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,125 @@
-# Temporary Holding Version
+# @ykurilov/agent-chat-flows
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Сценарии поведения агента. Разговор идёт по карте шагов — состояний. У каждого состояния своя короткая инструкция и
+условия выхода: словами (решает судья), по данным, по событию или по таймеру. Агент помнит карточку клиента между
+чатами и пишет первым, когда сработал таймер. Сценарий может идти по дням («программа на 3 дня»): ночь, касания, рамки
+дня, срок. Автор рисует сценарий в редакторе, проверяет и прогоняет его.
+
+Полное описание простыми словами, с примерами и замерами: [docs/flows.md](../../docs/flows.md).
+
+## Подключить
+
+```bash
+pnpm add @ykurilov/agent-chat-flows
+```
+
+```ts
+import { createAgentFlow } from "@ykurilov/agent-chat-flows";
+import { sqliteFlowStore } from "@ykurilov/agent-chat-flows/sqlite";
+
+const flow = createAgentFlow({
+  loadFlow: async ({ ownerId, chat }) => ({ flowId: "sales-review", versionId: "3", flow: publishedJson }),
+  store: sqliteFlowStore("./data/chat.db"),
+  judge: { fallback: { modelId: "deepseek-4.1-flash", providerId: "deepseek" } },
+});
+
+const { handler, service } = createChatServer(flow.withChat({ ...chatOptions, agent: { instructions, tools } }));
+flow.attach(service);
+flow.start();
+```
+
+Судья — `microsoft/microsoft-decision-1` через OpenRouter: нужен `OPENROUTER_API_KEY` на сервере. Запасная модель
+(`judge.fallback`) — из каталога приложения.
+
+## Настройки `createAgentFlow`
+
+| Настройка | Что это | По умолчанию |
+|---|---|---|
+| `loadFlow` | сценарий нового чата: `{ flowId, versionId, flow }` или `null` — без сценария. Перенос чата: `stateId`, `startedAt`, `enteredAt` | обязательна |
+| `store` | `memoryFlowStore()`, `sqliteFlowStore(path)`, `postgresFlowStore(pool)` | обязательна |
+| `judge.fallback` | запасная модель судьи из каталога | обязательна |
+| `judge.model`, `judge.threshold`, `judge.timeoutMs` | основной судья, порог «выполнено», срок | decision-1, 0,7, 5000 мс |
+| `judge.openrouter` | `{ apiKey, baseUrl, headers }`: свой прокси и его заголовки | из окружения |
+| `firstMessages` | тихие часы, потолок в сутки, `canWriteNow`; `false` — без часов и потолка. `canWriteNow` → `false` — «не сейчас», касание через час, `{ retryAt }` — в свой момент; конец разговора от него не зависит. «Дни и время» сценария главнее | 21:00–09:00, 3 в сутки |
+| `onTransition` | каждый переход: `from`, `to`, `exitId`, `decidedBy`, `tags`, `reason`, `day` | — |
+| `onFinish` | конец разговора: `reason` (`final`, `deadline`, `abandoned`, `blocked`), `day`, `state`, `tags`, `run` | — |
+| `clientCard` | карточка клиента в базе приложения: `read`, `write`, `forget` | таблица модуля |
+| `clientFacts` | свободные факты о человеке в карточке («ведёт блог»): `flow_note { fact }`, список в блоке `flow:client`, «забудь» стирает. Свои таблицы фактов — `clientCard.facts`; правило делит факты (карточка) и правила общения (память SDK) | выключено |
+| `people` | пояс человека в базе приложения: `readTimeZone`, `writeTimeZone` | таблица модуля |
+| `defaultTimeZone` | пояс, пока пояс человека неизвестен: человек → страница → он → `agent.timeZone` → сервер | — |
+| `pause.staffSilenceHours` | через сколько часов молчания сотрудника пауза снимается сама | 2 |
+| `timers` | `tickMs` — как часто смотреть таймеры, `leaseMs` — аренда копией сервера | 15 000 и 60 000 мс |
+| `logError` | строки журнала | `console.error` |
+| `now` | часы: тесты подменяют время целиком | сейчас |
+
+Что есть у `flow`: `withChat`, `attach`, `start`, `stop`, `settled`, `signal`, `adopt`, `end`, `admit`, `pause`, `resume`,
+`noteStaffReply` (реплика сотрудника — путём `service.appendStaffMessage`), `reportDelivery`, `readRun`, `chatsByState`,
+`migrateChats`, `readClientCard`, `forgetClientCard`, `advanceTestClock`, `tick` (один обход таймеров: тесты, свой
+планировщик). Из пакета — ещё `factId(text)`: id факта карточки.
+
+- `attach(service)` — одна служба на всё приложение. `attach({ portFor, deliver })` — служба на чат и своя доставка
+  того, что агент пишет первым. `deliver` получает текст (`text`) и все части ответа для человека (`parts`: карточка
+  ролика, картинка, файл, виджет — с 0.53) и возвращает исход: `delivered`, `retry`, `window_closed`, `blocked`, `failed`.
+- Каналы SDK сообщают исход сами: `createMessengers({ onAnswerDelivery: (report) => flow.reportDelivery(report) })`.
+- Недоставленное касание (`failed`, `window_closed`) не засчитывается: тот же шаг повторится через свой срок от момента
+  отказа. Пока ждёт повтор доставки, новых ходов нет.
+- Свой канал перед ходом зовёт `flow.admit`: ответить, ответить готовой фразой, промолчать до утра (после жёсткой рамки
+  дня), разговор закончен или отвечает сотрудник. Ночью агент человеку отвечает.
+- `flow.adopt` переносит идущий чат из вашей системы сразу, без хода: место, последние реплики, шаг касаний, счёт дня.
+- `flow.end({ reason: "switched" })` заканчивает разговор со своей причиной: `onFinish`, как у остальных концов.
+
+- Место чата (ключ `flow` в состоянии) посетителю не уходит: SDK прячет его сам (`privateStateKeys`). Читайте его
+  через `flow.readRun`.
+- В групповых чатах сценарий выключен. Сотрудник в песочнице карточку клиента только читает.
+- Лимит расходов проверяется до каждого обращения к судье: исчерпан — запроса нет, условие «не проверено».
+- `attach` ждёт службу чата с `assertWithinLimit` — её даёт `createChatServer` этой версии.
+
+## Тестовый чат
+
+`FlowTestChat` ждёт от приложения `start`, `advance`, `readRun` и `renderChat` (`FlowTestChatConnection`). На сервере это
+`service.createChat(userId, { data: flowTestChatData() })`, `flow.advanceTestClock` и `flow.readRun`. Кнопка «К началу
+следующего дня» — необязательный `advanceToNextDay`: на сервере `flow.advanceTestClock({ ownerId, chatId, to:
+"next_day_start" })`.
+
+`FlowEditor`: `readOnly` — доска только для просмотра, пока сценарий правит внешний агент; `onSave` может вернуть
+`{ ok: false, issues }` — отказ без исключения, находки встают у нод; `className` и `style` идут на корень, высота по
+умолчанию — родителя, не меньше разумной. Подробно — [docs/flows.md](../../docs/flows.md).
+
+Свои проверки приложения: `checks` у `FlowEditor` и `FlowTestChat`, на сервере те же — `checkFlow(flow, catalog, {
+checks })`. Поля приложения для карточки и попутных задач — `catalog.fields`.
+
+Эндпоинты тестового чата (advanceTestClock, readRun) приложение закрывает правами само: только редактору и только для
+тестовых чатов.
+
+## Входы
+
+| Вход | Что внутри |
+|---|---|
+| `.` | сервер: `createAgentFlow`, `memoryFlowStore`, `flowTestChatData`, всё из `./format` |
+| `./format` | формат (`parseFlow`, `compactFlow`), проверка (`checkFlow`, `FlowAppChecks`), движок — без серверных зависимостей, для браузера |
+| `./react` | `FlowEditor`, `FlowTestChat`, `ClientCardPanel`, договоры скинов, надписи ru/en |
+| `./sqlite`, `./postgres` | хранилище сценариев в базе приложения |
+| `./agent-flow.schema.json` | JSON Schema формата для внешних редакторов и агентов |
+
+Скины Тандема: `@ykurilov/agent-chat-skin-tandem/flows` (`tandemFlowEditorSkin`) и
+`@ykurilov/agent-chat-skin-tandem/client-card` (`tandemClientCardSkin`).
+
+## Хранилище
+
+Своё хранилище реализует договор `FlowStore`. С 0.49 в нём ещё `renewLease()` — продлить аренду чата перед ходом и во
+время него — и `setDue(chatId, due, { unlessDelivery })` — не затирать срок повтора доставки. Обход таймеров идёт до 5
+ходов одновременно.
+
+Таблицы `flow_chats`, `flow_versions`, `flow_client_cards`, `flow_first_messages`, `flow_people`, `flow_side_tasks` и свой журнал миграций
+`__flows_migrations`. Создаются сами при первом обращении. SQLite — файл может быть общим с чатами. PostgreSQL —
+схема `agent_chat` на пуле приложения, пул закрывает приложение.
+
+## Формат версии 2
+
+С 0.49 сценарий пишется версией 2: «Дни и время» (`schedule`), касания (`nudges` у сценария и у состояния), таймер
+`state_days`, поле «да/нет» (`boolean`), попутные задачи (`sideTasks`), режим после конца (`afterEnd`). Версия 1
+читается и переводится сама. Версия 0.48 JSON версии 2 не откроет. Образец со всеми частями —
+[demo/three-day-program.json](demo/three-day-program.json).
+
+С 0.55 к версии 2 добавился таймер «наступил день N программы» (`{ "type": "timer", "from": "program_day", "day": 3 }`):
+выход в начале дня N, когда бы человек ни пришёл в ноду. SDK до 0.55 такой сценарий не откроет.