@ykurilov/agent-chat-core 0.72.0 → 0.73.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @ykurilov/agent-chat-core
 
+## 0.73.0
+
+### Minor Changes
+
+- 34fec8f: Опциональный endTurn(output, { requireText: true }) завершает ход только при пользовательском тексте текущего ответа; иначе возвращает обычный output и даёт модели продолжить. Проверка по сборке потока в памяти, без чтения БД и flush. Whitespace, форматные невидимые Unicode, reasoning, tool output, ошибки и предыдущие ответы не считаются. SDK не добавляет собственную реплику. Прежний silent endTurn и явно переданный options.text сохранены.
+  
+  Как обновить приложение: обновить все пакеты SDK одной версией и включить requireText у нужных инструментов вместо проверки текста через хранилище. Инструкцию модели писать перед вызовом сохранить. Guard не отменяет сохранённые данные, не повторяет инструмент сам и не гарантирует текст при отмене, сбое или лимите. Миграций нет.
+
 ## 0.72.0
 
 No changes in this release.

package/README.md

@@ -78,7 +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`.
-- Конец хода сразу после инструмента: `execute` возвращает `endTurn(output, { text? })` — модель следующего шага не делает, готовый `text` идёт в ответ обычной текстовой частью без запроса к провайдеру и без расхода; `output` модель и запись видят как обычно. Тип `EndTurnOptions`.
+- Конец хода сразу после инструмента: `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`, ответ не пишется.
 - Набор виджетов по чату: `agent.widgets.enabledFor({ chat: { id, ownerId, data?, subject? } })` → имена включённых. Выключенных модель не видит (нет в инструментах запроса), их прошлые вызовы идут модели текстом. Синхронная, те же данные — тот же набор; смена набора сбрасывает кэш модели. Неизвестное имя — строка в журнал, исключение — ошибка хода. Подробно — [docs/widgets.md](../../docs/widgets.md).

package/dist/{chunk-YMUK7P4S.js → chunk-6KHSUGHE.js}

@@ -1342,13 +1342,20 @@ function endTurnNoteForModel(part) {
 function endTurn(output, options2) {
   const text = options2?.text;
   if (text !== void 0 && typeof text !== "string") throw new TypeError("endTurn: text \u2014 \u0441\u0442\u0440\u043E\u043A\u0430");
-  const mark = { [END_TURN]: true, output, text: text !== void 0 && text.trim().length > 0 ? text : void 0 };
+  if (options2?.requireText !== void 0 && typeof options2.requireText !== "boolean") throw new TypeError("endTurn: requireText must be a boolean");
+  const mark = { [END_TURN]: true, output, requireText: options2?.requireText === true, text: text !== void 0 && text.trim().length > 0 ? text : void 0 };
   return mark;
 }
 function isEndTurnMark(value) {
   return typeof value === "object" && value !== null && value[END_TURN] === true;
 }
-function createEndTurnRequests() {
+function hasUserFacingText(parts) {
+  return parts.some((part) => part.type === "text" && typeof part.text === "string" && hasText(part.text));
+}
+function hasText(text) {
+  return text.replace(/[\s\p{Cf}\p{Default_Ignorable_Code_Point}]/gu, "").length > 0;
+}
+function createEndTurnRequests(snapshot = async () => []) {
   let calls = 0;
   let attempt = 0;
   let silent = false;
@@ -1359,8 +1366,14 @@ function createEndTurnRequests() {
       const own = attempt;
       return withEndTurn(tools, (toolCallId) => {
         const order = calls++;
-        return (text) => {
-          if (own === attempt) ended.set(toolCallId, { order, text });
+        return (text, requireText) => {
+          const remember = () => {
+            if (own === attempt) ended.set(toolCallId, { order, text, requireText });
+          };
+          if (!requireText || text !== void 0 && hasText(text)) return remember();
+          return snapshot().then((parts) => {
+            if (hasUserFacingText(parts)) remember();
+          });
         };
       });
     },
@@ -1381,7 +1394,9 @@ function createEndTurnRequests() {
       attempt += 1;
       silent = false;
       const answered = new Set(parts.flatMap((part) => isAnsweredToolPart(part) ? [part.toolCallId] : []));
-      for (const toolCallId of ended.keys()) if (!answered.has(toolCallId)) ended.delete(toolCallId);
+      for (const [toolCallId, request] of ended) {
+        if (!answered.has(toolCallId) || request.requireText && !(request.text !== void 0 && hasText(request.text)) && !hasUserFacingText(parts)) ended.delete(toolCallId);
+      }
     }
   };
 }
@@ -1404,8 +1419,8 @@ function withEndTurn(tools, startCall) {
         const onEnd = startCall(options2.toolCallId);
         const unwrap = (value) => {
           if (!isEndTurnMark(value)) return value;
-          onEnd(value.text);
-          return value.output;
+          const accepted = onEnd(value.text, value.requireText === true);
+          return accepted ? accepted.then(() => value.output) : value.output;
         };
         const result = execute(input, options2);
         if (isAsyncIterable(result)) return unwrapEach(result, unwrap);
@@ -7163,7 +7178,7 @@ async function runTurn(turnInput, emitRaw) {
       ...input.recordChatClosure && { record: input.recordChatClosure }
     });
     const toolQueue = input.toolQueue ?? createToolQueue();
-    const endTurns = createEndTurnRequests();
+    const endTurns = createEndTurnRequests(() => saver.snapshot());
     let lastFinishReason;
     const browser = input.browserTools && createTurnBrowserTools({ ...input.browserTools, tabId: input.browserTools.tabId, chatId: input.chatId, emit: emitToClient, signal: input.abortSignal });
     let errors = [];
@@ -15167,4 +15182,4 @@ export {
   InvalidWidgetAnswerError,
   createChatService
 };
-//# sourceMappingURL=chunk-YMUK7P4S.js.map
+//# sourceMappingURL=chunk-6KHSUGHE.js.map