@ykurilov/agent-chat-flows 0.80.0 → 0.81.0

package/CHANGELOG.md

@@ -1,5 +1,99 @@
 # @ykurilov/agent-chat-flows
 
+## 0.81.0
+
+### Minor Changes
+
+- 58204d2: **Ломает приложения со своим хранилищем мессенджеров или сценариев.** Хранилища из пакетов (память, SQLite,
+  Postgres) уже готовы — если вы передаёте их, менять ничего не нужно.
+  
+  - `MessengerStore`: новый обязательный метод `saveLinkIfFree` и признак `guarded: true`. Привязка аккаунта по коду
+    идёт только через `saveLinkIfFree`: два кода разных людей на один аккаунт мессенджера больше не переписывают друг
+    друга.
+  - `FlowStore`: новый обязательный метод `swapDelivery` и признак `guarded: true`.
+  - Без `guarded: true` `createMessengers` и `createAgentFlow` сразу бросают `TypeError`. Признак — обещание, что
+    хранилище выполняет условия держателя и аренды (список — в шаге 3 ниже).
+  
+  Новое для своей доставки сценария (`attach({ deliver })`):
+  
+  - Исход `{ status: "await_repair" }` — канал сломан и ждёт починки (например, отозван токен бота). Ответ ждёт,
+    попытка не тратится, новых ходов и касаний нет. Починили — `flow.resumeDelivery({ ownerId, chatId, messageId })`:
+    тот же `messageId`, текст и части уходят ближайшим обходом таймеров. Ответ: `resumed`, `pending`, `busy`,
+    `not_found` или `dropped` (человек уже написал после ответа — ответ снят и помечен недоставленным). Ожидание
+    переживает перезапуск. В `reportDelivery` этот исход — `TypeError`.
+  - Пока идёт `deliver`, аренда чата продлевается: вторая копия сервера ту же попытку не начинает. Копия упала посреди
+    отправки — та же попытка повторяется через её паузу. Итог устаревшей копии не пишется.
+  - Перед самым `deliver`, уже под резервом, SDK ещё раз сверяет: разговор не закончен после хода (`flow.end`), ответ
+    есть в ветке, после починки человек не написал после него. Иначе `deliver` не зовётся, ответ помечен недоставленным.
+  - Повтор доставки прощания у законченного разговора теперь доходит — без нового хода и без открытия разговора.
+  - «Ровно один раз» снаружи SDK не обещает: после падения копии тот же ответ может уйти ещё раз с тем же `messageId`.
+    Двойную отправку отсекает приложение по `messageId`.
+  
+  Остальные исправления аудита работают без правок в приложении:
+  
+  - Ход группы мессенджера остаётся групповым и тогда, когда агент пишет первым, когда человек правит сообщение
+    группы, шлёт поправку к ходу или нажимает кнопку-подсказку: без памяти и личных блоков владельца, только
+    разрешённые группе инструменты, с пределом сообщений участника.
+  - Удаление чата ждёт хода на любой копии сервера: идёт ход — `ChatBusyError`, чат цел.
+  - Не удалось отметить вложения сообщения прикреплёнными — ошибка доходит до вызывающего, сообщение не записывается,
+    место в счёте сообщений отдаётся назад; повтор того же сообщения проходит.
+  - Сценарий, который не сходится с подтверждениями приложения (`confirmations`, `exitGuards`), проверяется до записи
+    версии и закрепления чата: чат идёт без сценария, перевод чатов на такую версию — отказ.
+  - Копия сервера, у которой забрали аренду таймера сценария или обновления мессенджера, больше не шлёт касание и не
+    переписывает срок и итог другой копии.
+  
+  ### Как обновить приложение
+  
+  Нужно только если приложение передаёт в `createMessengers` или `createAgentFlow` своё хранилище (не
+  `createMemoryMessengerStore`, `createSqliteMessengerStore`, `createPostgresMessengerStore`, `memoryFlowStore`,
+  `sqliteFlowStore`, `postgresFlowStore`).
+  
+  1. Найдите свою реализацию `MessengerStore` (поиск по `MessengerStore` или `saveLink(`).
+  2. Добавьте метод — одной атомарной операцией базы:
+  
+     ```ts
+     async saveLinkIfFree(link) {
+       // Аккаунт свободен или уже за link.userId — записать (имя и время обновить) и вернуть "saved".
+       // Аккаунт за другим пользователем — ничего не менять и вернуть "taken".
+     }
+     ```
+  
+     В SQL это `insert … on conflict (messenger, bot_id, external_user_id) do update set … where user_id = $userId
+     returning …`: строка вернулась — `"saved"`, нет — `"taken"`. Отдельные «найти, потом записать» не годятся: между
+     ними успевает второй код.
+  3. Добавьте признак `guarded: true` в объект хранилища. Он обещает:
+     - `finishUpdate(key, status, now, holder)`, `renewUpdates` и `releaseUpdate` пишут, только пока обновление за этим
+       держателем; `acquireLease` не отдаёт чужую живую аренду;
+     - `saveLinkIfFree` — одна атомарная операция.
+  4. Своё `FlowStore` (если есть): метод `swapDelivery(chatId, { expected, next, due, claim, freeAt, endedAt })` одной
+     транзакцией. Заменить запись доставки, только если сейчас там `expected` (совпали `messageId`, `attempt` и `token`;
+     `null` — записи нет). С `claim` — только если аренда чата свободна, уже у `claim.owner` или у `claim.from`, и взять
+     её до `now + leaseMs`. С `freeAt` — только если живой аренды нет. С `endedAt` — только если конец разговора всё
+     ещё этот (`null` — не закончен). `due` записать вместе с записью. Вернуть `true`,
+     если заменил этот вызов. Плюс `guarded: true`, который обещает:
+     - `setDue(…, { leaseOwner })` пишет, только пока аренда у этой копии; `{ unlessDelivery: true }` — только если
+       доставки не ждёт;
+     - `leaseDue` не берёт живую аренду, а законченные разговоры берёт только со сроком `FLOW_DELIVERY_EXIT`;
+     - `endChat` при ждущей доставке не снимает срок и аренду.
+     Образец — `postgresFlowStore` и `sqliteFlowStore` в `@ykurilov/agent-chat-flows`.
+  5. Проверка: `pnpm typecheck` проходит. Без признака или без `saveLinkIfFree` запуск сразу бросает `TypeError` с
+     подсказкой, без `swapDelivery` — `attach({ deliver })`.
+
+### Patch Changes
+
+- Updated dependencies [038b6e2]
+- Updated dependencies [58204d2]
+  - @ykurilov/agent-chat-react@0.81.0
+  - @ykurilov/agent-chat-core@0.81.0
+
+## 0.80.1
+
+### Patch Changes
+
+- Updated dependencies [d59ae4e]
+  - @ykurilov/agent-chat-core@0.80.1
+  - @ykurilov/agent-chat-react@0.80.1
+
 ## 0.80.0
 
 ### Patch Changes

package/dist/{chunk-CZ3EDVYW.js → chunk-7ES2PXNH.js}

@@ -606,7 +606,7 @@ function createFlowFinish(input) {
         ...text && { reply: { text } }
       });
       if (result.status !== "delivered" || !result.turnStarted) return;
-      if (delivery) await delivery.afterFirstTurn({ ownerId, chatId, answer: result.answer, reasons: [{ kind: "farewell" }], at, timeZone });
+      if (delivery) await delivery.afterFirstTurn({ ownerId, chatId, answer: result.answer, reasons: [{ kind: "farewell" }], at, timeZone, endedAt: record?.endedAt ?? null });
       else await firstMessages?.record({ ownerId, at, timeZone });
     },
     async end({ ownerId, chatId, pinned, run, reason, outcome, at }) {
@@ -835,4 +835,4 @@ export {
   clientFactStore,
   factEntry
 };
-//# sourceMappingURL=chunk-CZ3EDVYW.js.map
+//# sourceMappingURL=chunk-7ES2PXNH.js.map