@ykurilov/agent-chat-core 0.79.1 → 0.80.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @ykurilov/agent-chat-core
 
+## 0.80.0
+
+### Minor Changes
+
+- 2cc8429: Добавлена серверная настройка `agent.contextBlocksRefresh: "history-start"`: блоки приложения читаются при первом снимке и после смены начала видимой истории, используя существующий frozen context ветки. Между этими событиями источник не вызывается и изменённые данные приложения не досылаются модели. По умолчанию и при `"turn"` поведение прежнее. Перезапуск и ветки используют сохранённый снимок; продолжение с выполненными шагами сохраняет frozen context. Retry без завершённых шагов создаёт новый ответ и может заново прочитать источник. Ошибка источника сохраняет fallback и оставляет следующей новой сборке повторную попытку.
+  
+  ### Как обновить приложение
+  
+  Обновите установленные пакеты SDK одной версией. Если профиль должен застывать как память, добавьте `contextBlocksRefresh: "history-start"` рядом с `contextBlocks`. Изменения вне переписки передавайте через `prepareTurn.notices`; права по-прежнему проверяйте сервером. Для классификации каждого вопроса оставьте `"turn"`. Никаких SQL-миграций или собственного кэша не требуется. [Триггеры, ограничения и пример](https://github.com/ykurilov/agent-chat-sdk/blob/main/docs/context-blocks-refresh.md).
+
 ## 0.79.1
 
 No changes in this release.

package/README.md

@@ -78,6 +78,7 @@ import type { ChatStorage } from "@ykurilov/agent-chat-core";
 - Снимок перед каждым шагом: `agent.stepContext: ({ state, stepNumber, chat, subject, … }) => string | null` — текст ложится сообщением человека в самый конец запроса шага, после результатов инструментов, в историю не пишется. Снимок на шаге один, всё до него от шага к шагу те же байты (кэш модели). `null` — шаг без снимка, бросок — без снимка и строка в журнал. Функция видит те же `channel`, `audience`, `staff`, что инструменты (в группе личного не показывайте), данные чата — копиями. Срок `agent.stepContextTimeoutMs` (по умолчанию 5 с): не ответила — шаг без снимка, `abortSignal` отменён. Типы `StepContext`, `StepContextInput`.
 - Застывающий контекст: память, сегодняшняя дата, место на экране и блоки приложения вписываются в вопрос человека один раз за ход и дальше не меняются ни на байт. Следующий ход побайтно начинается с последнего шага прошлого (с рассуждениями и инструментами), поэтому всё прошлое читается из кэша модели. В новый вопрос идут только изменившиеся блоки и строка `[Больше не действует: «ключ»]` про пропавшие. Источник может вернуть `{ key, hidden: true }` — блок есть, но не показан ради места: вместо «больше не действует» модель, видевшая его, получит `[Не показано ради места, но по-прежнему действует: «ключ»]`. Набор хода хранится служебной частью ответа `data-frozen-context` (`FROZEN_CONTEXT_PART_TYPE`): в поток, историю, `afterTurn` и поиск по истории она не уходит. Продолжение после подтверждения, автопродолжение, запасной провайдер и «Повторить» берут блоки из ответа и источники заново не опрашивают. Память строже остальных блоков: читается один раз на чат — в первом ходе, после сжатия истории, при смене начала истории (правка первого сообщения, «Переделать» первого ответа), в первом личном ходе после группового и после сбоя чтения — и в идущем чате не перечитывается и не досылается (ни изменения, ни новые записи, ни «Больше не действует»); `snapshot()` и `blocks()` в остальных ходах не зовутся. Своя долгая память может отдавать блоки по записям: `LongTermMemory.blocks?({ userId, chatId })`; без него — один блок из `snapshot()`.
 - Блоки приложения в вопросе хода: `agent.contextBlocks: ({ chatId, ownerId, chat, state, subject, channel, audience, … }) => [{ key, text, private? }] | null` — список скиллов, роль, правила. Зовётся один раз в начале хода; текст вписывается в вопрос после памяти и даты и дальше не меняется ни на байт (кэш модели), ядро его не оборачивает. На следующих ходах в вопрос идут только изменённые блоки целиком и строка `[Больше не действует: «ключ»]` про убранные. Ключи `memory`, `memory:*`, `today`, `screen_place` заняты ядром: такой блок отбрасывается со строкой в журнал. `private: true` — в групповом ходе блок не показывается. Срок `agent.contextBlocksTimeoutMs` (по умолчанию 5 с; 0 или `Infinity` — без срока, иначе от 1000): не ответила или бросила — блоки приложения берутся из прошлого ответа, в журнал строка `[блоки контекста] …`, `abortSignal` отменён; «Стоп» — без строки. Блоки хранятся служебной частью ответа: в потоке, истории, `afterTurn` и поиске по истории её нет. Типы `ContextBlock`, `ContextBlocksInput`, `ContextBlocksSource`, `HiddenContextBlock`, `ContextBlockEntry`.
+- `agent.contextBlocksRefresh: "history-start"` включает снимок приложения до смены начала видимой истории, как у памяти. Без настройки и при `"turn"` источник по-прежнему читается каждый новый ход. Снимок хранится в frozen context ветки; своего кэша или SQL-миграций не требуется. Изменения вне переписки передаются через `prepareTurn.notices`, права проверяются сервером. [Триггеры, ошибки и пример](https://github.com/ykurilov/agent-chat-sdk/blob/main/docs/context-blocks-refresh.md).
 - Конец хода сразу после инструмента: `execute` возвращает `endTurn(output, { text? })` — модель следующего шага не делает, готовый `text` идёт в ответ обычной текстовой частью без запроса к провайдеру и без расхода; `output` модель и запись видят как обычно. Тип `EndTurnOptions`. С `endTurn(output, { requireText: true })` остановка принимается только при непустом пользовательском text-part текущего ответа; без него результат обычный и модель продолжает. Проверка в памяти потока, без чтения БД/flush. Пробелы и чисто форматные невидимые Unicode, reasoning, tool output, ошибки и прежняя история не считаются; Markdown/HTML по смыслу не разбирается. Явный непустой `options.text` сохраняет приоритет и прежний путь готового текста. Это не автоподтверждение и не гарантия ответа при отмене, лимите или сбое. [Полная семантика и переход](../../docs/in-product-agent.md#14-конец-хода-сразу-после-инструмента).
 - Данные чата без записи: `service.getChatData(userId, chatId)` — копия, проверки владения как у `updateChatData`.
 - Проверка ответа виджета на сервере: `checkAnswer(answer, ctx)` у своего виджета и общая `agent.widgets.checkAnswer(call, answer, ctx)` (для всех виджетов без своей). Зовётся после схемы под замком чата. Исход: `undefined` — принять, `{ answer }` — принять с заменой, `{ refuse: "текст" }` — отказать (`WidgetAnswerRefusedError`, сервер — 409 `widget_answer_refused`, виджет остаётся открытым). `ctx` — `ownerId`, `chatId`, `messageId`, `toolName`, `toolCallId`, `input`, `subject?`, `chatData?`, `state` (записи ложатся в ответ вместе с результатом виджета, хук `onStateChanged` — с причиной `widgetAnswer`), `emitAppEvent` (событие приложения вместе с ответом виджета), `signal` (отмена по сроку или «Стопу»: приложение слушает его само). Срок — `agent.widgets.checkAnswerTimeoutMs` (5 000 мс, заметно меньше `requestTimeoutMs` страницы). Исключение — 500, ничего не записано, в журнале только имя ошибки; срок вышел — `WidgetAnswerCheckTimeoutError`, сервер — 504 `widget_check_timeout`. Чат закрыли во время проверки — `ChatClosedError`, ответ не пишется.

package/dist/{chunk-AJSRGBVM.js → chunk-Z44ZAFZC.js}

@@ -6918,25 +6918,29 @@ function appBlocksSource(options2) {
 // src/frozen-context/freeze-context.ts
 var sourceOf = (key) => isMemoryKey(key) ? "memory" : isReservedKey(key) ? "core" : "app";
 async function freezeContext(input) {
-  const { chatId, sources, base, signal, memoryFrom } = input;
+  const { chatId, sources, base, signal, memoryFrom, appContextFrom } = input;
   const log = input.logError ?? console.error;
   const fromBase = (source) => base?.data.blocks.filter((block) => sourceOf(block.key) === source) ?? [];
-  const read = async (source, fetch) => {
-    if (!fetch) return { blocks: fromBase(source), fresh: false };
+  const read = async (source, fetch, from) => {
+    const previous = source === "memory" ? base?.data.memoryFrom : base?.data.appContextFrom;
+    const kept = from !== void 0 && previous === from;
+    if (kept || !fetch) return { blocks: fromBase(source), ...kept && { from } };
     try {
       const blocks2 = await fetch();
       if (blocks2 !== null && blocks2 !== void 0 && !Array.isArray(blocks2)) throw new TypeError(`\u0436\u0434\u0451\u043C \u0441\u043F\u0438\u0441\u043E\u043A \u0431\u043B\u043E\u043A\u043E\u0432, \u0430 \u043F\u0440\u0438\u0448\u043B\u043E ${typeof blocks2}`);
-      return { blocks: blocks2 ?? [], fresh: true };
+      return { blocks: blocks2 ?? [], ...from !== void 0 && { from } };
     } catch (error) {
       if (!signal?.aborted) log(`[\u0431\u043B\u043E\u043A\u0438 \u043A\u043E\u043D\u0442\u0435\u043A\u0441\u0442\u0430] \u0447\u0430\u0442=${chatId} \u0438\u0441\u0442\u043E\u0447\u043D\u0438\u043A=${source} \u0441\u0431\u043E\u0439: ${error instanceof Error ? error.message : "\u043D\u0435\u0438\u0437\u0432\u0435\u0441\u0442\u043D\u0430\u044F \u043E\u0448\u0438\u0431\u043A\u0430"}; \u0431\u043B\u043E\u043A\u0438 \u0438\u0437 \u043F\u0440\u043E\u0448\u043B\u043E\u0433\u043E \u0445\u043E\u0434\u0430`);
-      return { blocks: fromBase(source), fresh: false };
+      return { blocks: fromBase(source) };
     }
   };
-  const memoryKept = memoryFrom !== void 0 && base?.data.memoryFrom === memoryFrom;
-  const [memoryRead, appRead] = await Promise.all([read("memory", memoryKept ? void 0 : sources.memory), read("app", sources.app)]);
+  const [memoryRead, appRead] = await Promise.all([read("memory", sources.memory, memoryFrom), read("app", sources.app, appContextFrom)]);
   const memory = memoryRead.blocks;
   const app = appRead.blocks;
-  const memoryMark = memoryFrom !== void 0 && (memoryKept || memoryRead.fresh) ? { memoryFrom } : {};
+  const marks = {
+    ...memoryRead.from !== void 0 && { memoryFrom: memoryRead.from },
+    ...appRead.from !== void 0 && { appContextFrom: appRead.from }
+  };
   const accepted = /* @__PURE__ */ new Set();
   const hidden = /* @__PURE__ */ new Set();
   const accept = (block, source) => {
@@ -6962,7 +6966,7 @@ async function freezeContext(input) {
   accepted.add(SCREEN_PLACE_KEY);
   blocks.push(...app.filter((block) => accept(block, "app")).map(copyBlock));
   if (sources.place) blocks.push({ key: SCREEN_PLACE_KEY, text: sources.place });
-  if (!base) return { blocks, sent: "all", base: null, ...memoryMark };
+  if (!base) return { blocks, sent: "all", base: null, ...marks };
   const before = new Map(base.data.blocks.map((block) => [block.key, block.text]));
   const keys = new Set(blocks.map((block) => block.key));
   const gone = base.data.blocks.filter((block) => !keys.has(block.key)).map((block) => block.key);
@@ -6975,7 +6979,7 @@ async function freezeContext(input) {
       ...hiddenNow.length > 0 && { hidden: hiddenNow }
     },
     base: base.id,
-    ...memoryMark
+    ...marks
   };
 }
 function copyBlock(block) {
@@ -6993,7 +6997,7 @@ async function resumeNoteForTurn(input, turn) {
   if (!seen) return void 0;
   const place = input.samePlace ? seen.blocks.find((block) => block.key === SCREEN_PLACE_KEY)?.text ?? null : screenPlaceBlock(input.place);
   const note = await freezeTurnContext(input, turn, { id: turn.answer.id, data: seen }, place);
-  return hasNewBlocks(note) ? note : void 0;
+  return hasNewBlocks(note) || note.appContextFrom !== seen.appContextFrom ? note : void 0;
 }
 async function freezeTurnContext(input, turn, base, place) {
   const sources = {
@@ -7027,11 +7031,13 @@ async function freezeTurnContext(input, turn, base, place) {
       }
     });
   }
+  const historyStart = turn.history[0]?.id ?? input.messageId;
   return freezeContext({
     chatId: input.chatId,
     sources,
     // Начало видимой истории: то же — память из базы; после сжатия другое — память заново. Агент говорит первым — сам ответ.
-    memoryFrom: turn.history[0]?.id ?? input.messageId,
+    memoryFrom: historyStart,
+    ...input.contextBlocksRefresh === "history-start" && { appContextFrom: historyStart },
     base,
     signal: input.abortSignal,
     ...input.logError && { logError: input.logError }
@@ -7232,7 +7238,17 @@ async function runTurn(turnInput, emitRaw) {
       let resumeNote = resume && !resume.replay && !frozen.fresh ? await resumeNoteForTurn(input, { history: answer.request().history, answer: resume.message, state: publicAppState(appState.values()), ...viewer && { viewer } }) : void 0;
       if (resume && turnNotices && !frozen.fresh) {
         const seen = latestFrozenContextOf(resume.message.parts);
-        if (seen) resumeNote = { ...resumeNote ?? { blocks: seen.blocks, sent: { changed: [], removed: [] }, base: messageId }, notices: turnNotices };
+        if (seen) {
+          resumeNote = {
+            ...resumeNote ?? {
+              blocks: seen.blocks,
+              sent: { changed: [], removed: [] },
+              base: messageId,
+              ...input.contextBlocksRefresh === "history-start" && seen.appContextFrom !== void 0 && { appContextFrom: seen.appContextFrom }
+            },
+            notices: turnNotices
+          };
+        }
       }
       const outages = input.providerOutages ?? createProviderOutages({ now: () => (input.now ?? (() => /* @__PURE__ */ new Date()))().getTime(), logError });
       const allFallbackIds = fallbackProviders({
@@ -7843,6 +7859,7 @@ async function openAttempt(input, attempt, attemptSignal) {
     stepContext,
     stepContextTimeoutMs,
     contextBlocks: _contextBlocks,
+    contextBlocksRefresh: _contextBlocksRefresh,
     contextBlocksTimeoutMs: _contextBlocksTimeoutMs,
     ...requestInput
   } = input;
@@ -12904,6 +12921,9 @@ function createChatService(input) {
     prepareTurn,
     ...agentSettings
   } = options2.agent;
+  if (agentSettings.contextBlocksRefresh !== void 0 && agentSettings.contextBlocksRefresh !== "turn" && agentSettings.contextBlocksRefresh !== "history-start") {
+    throw new TypeError('agent.contextBlocksRefresh: \u0436\u0434\u0451\u043C "turn" \u0438\u043B\u0438 "history-start"');
+  }
   const stepContextTimeoutMs = resolveTimeoutMs(stepContextTimeoutSetting, DEFAULT_STEP_CONTEXT_TIMEOUT_MS, "agent.stepContextTimeoutMs");
   const contextBlocksTimeoutMs = resolveTimeoutMs(contextBlocksTimeoutSetting, DEFAULT_CONTEXT_BLOCKS_TIMEOUT_MS, "agent.contextBlocksTimeoutMs");
   const turnLimits = resolveTurnLimits({ turnTimeoutMs, maxOutputTokens }, options2.catalog);
@@ -15303,4 +15323,4 @@ export {
   InvalidWidgetAnswerError,
   createChatService
 };
-//# sourceMappingURL=chunk-AJSRGBVM.js.map
+//# sourceMappingURL=chunk-Z44ZAFZC.js.map