@ykurilov/agent-chat-core 0.107.2 → 0.109.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -188,7 +188,7 @@ export interface AgentTurnInput {
188
188
  */
189
189
  replyChecks?: TurnReplyChecks;
190
190
  /**
191
- * Снимок перед каждым шагом модели: сообщением человека в самый конец запроса шага, в историю не пишется. Всё до него
191
+ * Снимок перед каждым шагом модели: служебным блоком в самый конец запроса шага, в историю не пишется. Всё до него
192
192
  * от шага к шагу не меняется (кэш модели). Нет — запрос побайтно прежний.
193
193
  */
194
194
  stepContext?: StepContext;
@@ -32,10 +32,21 @@ export interface StepContextInput {
32
32
  abortSignal: AbortSignal;
33
33
  }
34
34
  /**
35
- * Снимок перед каждым шагом модели: текст ложится сообщением человека в самый конец запроса шага, в историю не пишется.
36
- * Пустая строка, `null` или `undefined` — шаг без снимка.
35
+ * Снимок перед каждым шагом модели: текст ложится в самый конец запроса шага служебным блоком `<step_context>` с
36
+ * постоянным заголовком (`stepContextBlock`), в историю не пишется. Пустая строка, `null` или `undefined` — шаг без
37
+ * снимка.
37
38
  */
38
39
  export type StepContext = (input: StepContextInput) => string | null | undefined | Promise<string | null | undefined>;
40
+ /** Тег служебного блока снимка: модель, повторившая блок в ответе, его не покажет (`CORE_SERVICE_BLOCKS`). */
41
+ export declare const STEP_CONTEXT_TAG = "step_context";
42
+ /**
43
+ * Заголовок снимка. Снимок идёт сообщением роли «человек», на шагах после инструмента — сразу за результатом вызова:
44
+ * голые строки приложения модель принимала за новое сообщение человека без слов и отвечала «жду вашего ответа»
45
+ * (DeepSeek, 49 ходов из 103). Текст постоянный — меняется только снимок, а он и так в конце запроса.
46
+ */
47
+ export declare const STEP_CONTEXT_LEAD = "\u0421\u043B\u0443\u0436\u0435\u0431\u043D\u044B\u0435 \u0441\u0442\u0440\u043E\u043A\u0438 \u043F\u0440\u0438\u043B\u043E\u0436\u0435\u043D\u0438\u044F \u043A \u044D\u0442\u043E\u043C\u0443 \u0448\u0430\u0433\u0443 \u043E\u0442\u0432\u0435\u0442\u0430. \u042D\u0442\u043E \u043D\u0435 \u043D\u043E\u0432\u043E\u0435 \u0441\u043E\u043E\u0431\u0449\u0435\u043D\u0438\u0435 \u0447\u0435\u043B\u043E\u0432\u0435\u043A\u0430: \u043E\u043D \u0438\u0445 \u043D\u0435 \u043F\u0438\u0441\u0430\u043B \u0438 \u043D\u0435 \u0432\u0438\u0434\u0438\u0442 \u0438 \u043E\u0442\u0432\u0435\u0442\u0430 \u043D\u0430 \u043D\u0438\u0445 \u043D\u0435 \u0436\u0434\u0451\u0442. \u0425\u043E\u0434 \u0442\u043E\u0442 \u0436\u0435: \u043F\u0440\u043E\u0434\u043E\u043B\u0436\u0430\u0439 \u043E\u0442\u0432\u0435\u0447\u0430\u0442\u044C \u043D\u0430 \u043F\u043E\u0441\u043B\u0435\u0434\u043D\u0435\u0435 \u0441\u043E\u043E\u0431\u0449\u0435\u043D\u0438\u0435 \u0447\u0435\u043B\u043E\u0432\u0435\u043A\u0430 \u0432\u044B\u0448\u0435.";
48
+ /** Текст снимка так, как его видит модель: тег, заголовок, строки приложения как есть. */
49
+ export declare function stepContextBlock(text: string): string;
39
50
  export interface StepSnapshots {
40
51
  /**
41
52
  * Сообщения шага: снимок прошлого шага убран, новый — перед `trailing` последними сообщениями (служебная пометка
@@ -41,6 +41,7 @@ import type { ModelCatalog } from "./models/model-catalog.js";
41
41
  import { InvalidModelChoiceError } from "./models/model-choice.js";
42
42
  import type { ModelChoice, ModelMenu } from "./models/model-choice.js";
43
43
  import type { RunningAnswerRegistry } from "./running-answers/running-answer-registry.js";
44
+ import { STOP_REQUESTS_CHECK_EVERY_MS } from "./running-answers/stop-requests.js";
44
45
  import { SpendingLimitReachedError } from "./spending/spending-limits.js";
45
46
  import type { SpendingLimits, SpendingStatus } from "./spending/spending-limits.js";
46
47
  import type { ChatDataFilter } from "./storage/chat-data.js";
@@ -66,6 +67,7 @@ export interface VoiceTagSource {
66
67
  tagsOf(voiceId: string): VoiceTagSet | undefined;
67
68
  }
68
69
  export { InvalidModelChoiceError };
70
+ export { STOP_REQUESTS_CHECK_EVERY_MS };
69
71
  export { AttachmentRejectedError, SpendingLimitReachedError, TooManyTurnsError };
70
72
  export type { CompactionMarker, CompactionOutcome, CompactionSettings, ModelChoice, ModelMenu, SpendingLimits, SpendingStatus };
71
73
  export interface AgentSettings {
@@ -204,8 +206,8 @@ export interface AgentSettings {
204
206
  */
205
207
  cacheMissLog?: false;
206
208
  /**
207
- * Снимок перед каждым шагом модели: текст ложится сообщением человека в самый конец запроса шага, после результатов
208
- * инструментов, и в историю не пишется. Видит живое состояние ветки (`state`, записи прошлых шагов уже в нём), данные
209
+ * Снимок перед каждым шагом модели: текст ложится в самый конец запроса шага, после результатов инструментов, служебным
210
+ * блоком `<step_context>` с постоянным заголовком «это не новое сообщение человека», и в историю не пишется. Видит живое состояние ветки (`state`, записи прошлых шагов уже в нём), данные
209
211
  * и объект чата, номер шага. Всё до снимка от шага к шагу не меняется (кэш модели). `null` или пустая строка — шаг без
210
212
  * снимка; бросок — шаг без снимка и строка в журнал. Не задано — запрос побайтно прежний.
211
213
  */
@@ -932,8 +934,16 @@ export interface ChatService {
932
934
  answerBrowserCall(userId: string, chatId: string, toolCallId: string, answer: BrowserCallAnswer): Promise<void>;
933
935
  /** Поток идущего ответа с начала; `null`, если хода нет. */
934
936
  subscribe(userId: string, chatId: string): Promise<ReadableStream<UIMessageChunk> | null>;
935
- /** Останавливает идущий ответ; ход, который ещё запускается, остановится сразу после старта. `false`, если хода нет. */
936
- stop(userId: string, chatId: string): Promise<boolean>;
937
+ /**
938
+ * Останавливает идущий ответ; ход, который ещё запускается, остановится сразу после старта. `false`, если хода нет.
939
+ * С `turnRequestId` (id запроса хода, `TurnRequestContext.turnRequestId`) — только ход этого запроса, как бы ни легли
940
+ * запросы: пришедший раньше хода «Стоп» запоминается (и в хранилище, для других копий сервера), и ход остановится,
941
+ * как только начнётся; идущий на другой копии — на её ближайшей сверке (`STOP_REQUESTS_CHECK_EVERY_MS`). Ход другого
942
+ * запроса он не трогает. Ответ — `true`: «Стоп» принят.
943
+ */
944
+ stop(userId: string, chatId: string, stopOptions?: {
945
+ turnRequestId?: string;
946
+ }): Promise<boolean>;
937
947
  /**
938
948
  * Брошенные ответы — `streaming` без знака жизни дольше `ANSWER_STALE_AFTER_MS` (копия сервера упала или выключена) —
939
949
  * переводит в `interrupted`, написанное не трогает, незаписанный расход пишет в журнал. Живые ответы, в том числе
@@ -47,7 +47,7 @@ export { migratePostgresSchema } from "./storage/postgres-migrations.js";
47
47
  export { applyEmbeddedMigrations } from "./storage/embedded-migrations.js";
48
48
  export type { EmbeddedMigration, EmbeddedMigrationConfig } from "./storage/embedded-migrations.js";
49
49
  export type { PostgresMigrationConnection, PostgresMigrationOptions } from "./storage/postgres-migrations.js";
50
- export type { ChatTurnWriteGuard, AwaitingMessagePatch, ChatListOptions, ChatStorage, ChatSubjectFilter, FinishedMessagePatch, ImportedChat, MessageLink, MessagePartsLink, NewChatInput, SpendingLimitStateRecord, StoredPendingBurst, StreamingMessagePatch, } from "./storage/chat-storage.js";
50
+ export type { ChatTurnWriteGuard, AwaitingMessagePatch, ChatListOptions, ChatStorage, ChatSubjectFilter, FinishedMessagePatch, ImportedChat, MessageLink, MessagePartsLink, NewChatInput, SpendingLimitStateRecord, StoredPendingBurst, StoredStopRequest, StreamingMessagePatch, } from "./storage/chat-storage.js";
51
51
  export { SpendingLimitReachedError } from "./spending/spending-limits.js";
52
52
  export { APP_EVENT_DATA_MAX_BYTES, APP_EVENT_TYPE_MAX_LENGTH, isTurnRefusalCode, normalizeTurnRefusal, TURN_REFUSAL_MESSAGE_MAX_LENGTH, TurnRefusedError, validateAppEvent, } from "./turn-hooks/turn-hooks.js";
53
53
  export { DEFAULT_AFTER_TURN_ATTEMPTS, DEFAULT_AFTER_TURN_TIMEOUT_MS } from "./turn-hooks/after-turn.js";
@@ -83,6 +83,7 @@ export { createRequestOriginCheck, isSafeMethod, originRefusalHint } from "./req
83
83
  export type { OriginRefusal, RequestOriginCheck, RequestOriginCheckOptions } from "./request-origin/request-origin.js";
84
84
  export { createInMemoryChatStorage } from "./storage/in-memory-storage.js";
85
85
  export { ChatBusyError, createRunningAnswerRegistry } from "./running-answers/running-answer-registry.js";
86
+ export { STOP_REQUESTS_CHECK_EVERY_MS } from "./running-answers/stop-requests.js";
86
87
  export type { RunningAnswerRegistry } from "./running-answers/running-answer-registry.js";
87
88
  export { ChatNotFoundError, createChatService, InvalidMessageError, InvalidModelChoiceError, NothingToRetryError, } from "./chat-service.js";
88
89
  export type { AbandonedBurstsOptions, ActionOptions, AgentSettings, ChatBranchForks, ChatCompactions, ChatHistory, ChatListItem, ChatService, ChatInstructions, ChatInstructionsTurn, ChatState, CompactionMarker, CompactionOutcome, CompactionSettings, FlushOptions, CheckReplyInput, CheckReplyResult, IncomingUserMessage, ModelChoice, ModelChosenHandler, ModelMenu, RecoverInterruptedAnswersOptions, SendMessageOptions, SendBurstOptions, BurstMessageResult, SteerResult, } from "./chat-service.js";
@@ -121,7 +122,7 @@ export { CORE_SERVICE_BLOCKS, checkServiceBlockFormats, cutForgedBlocks, service
121
122
  export type { ServiceBlockFormat } from "./agent-run/forged-blocks.js";
122
123
  export { DEFAULT_MODEL_SILENCE } from "./provider-errors/model-silence.js";
123
124
  export type { ModelSilenceLimits, ModelSilenceSetting } from "./provider-errors/model-silence.js";
124
- export { APP_CHANGE_PART_TYPE, BROWSER_CALL_PART_TYPE } from "./page-context/page-context.js";
125
+ export { APP_CHANGE_PART_TYPE, BROWSER_CALL_PART_TYPE, isTurnRequestId } from "./page-context/page-context.js";
125
126
  export type { DataChange, ScreenPlace, TurnRequestContext } from "./page-context/page-context.js";
126
127
  export { isScreenPlaceInput, isTabId } from "./agent-run/screen-place.js";
127
128
  export { BrowserCallNotPendingError } from "./agent-run/browser-tools.js";
@@ -12,13 +12,20 @@ export interface DataChange {
12
12
  /** JSON до 4 КБ. */
13
13
  details?: unknown;
14
14
  }
15
- /** С чем пришёл запрос хода: место на экране, вкладка, которая его отправила, и часовой пояс человека. */
15
+ /** С чем пришёл запрос хода: место на экране, вкладка, которая его отправила, часовой пояс человека и id запроса. */
16
16
  export interface TurnRequestContext {
17
17
  place?: ScreenPlace | null;
18
18
  tabId?: string;
19
19
  /** Пояс браузера человека (`Intl.DateTimeFormat().resolvedOptions().timeZone`): по нему дата в запросе. Не IANA — не берётся. */
20
20
  timeZone?: string;
21
+ /**
22
+ * Id запроса хода от клиента (`isTurnRequestId`), новый на каждый запрос. «Стоп» с тем же id (`ChatService.stop`)
23
+ * останавливает именно этот ход — даже если пришёл раньше, чем ход начался, или на другую копию сервера.
24
+ */
25
+ turnRequestId?: string;
21
26
  }
27
+ /** Годится ли строка в id запроса хода: 1–100 знаков из латиницы, цифр, `_`, `-`, `.`, `:` (UUID подходит). */
28
+ export declare function isTurnRequestId(value: unknown): value is string;
22
29
  /**
23
30
  * Запрос страницы для продолжения после поправок на лету. Вкладка и пояс — последней присланной страницы: браузерные
24
31
  * инструменты продолжения идут на вкладку последней поправки. Место — последней поправки, где оно есть (`null` — «места
@@ -0,0 +1,38 @@
1
+ import type { ChatStorage } from "../storage/chat-storage.js";
2
+ /**
3
+ * «Стоп» по id запроса хода (`TurnRequestContext.turnRequestId`). Человек жмёт «Стоп» сразу после отправки: запрос
4
+ * остановки может прийти раньше, чем служба начала ход, или на другую копию сервера. Остановка запоминается по id
5
+ * запроса — в памяти копии и в хранилище, — и ход с этим id останавливается, как только начнётся или узнает о ней.
6
+ * Следующий запрос несёт новый id: чужой «Стоп» его не остановит.
7
+ */
8
+ /** Как часто идущий ход сверяется с хранилищем: не пришёл ли его «Стоп» на другую копию. */
9
+ export declare const STOP_REQUESTS_CHECK_EVERY_MS = 2000;
10
+ /**
11
+ * Сколько помнить «Стоп»: ход запроса начинается за секунды, идущий на другой копии узнаёт о нём за 2 с — час с
12
+ * большим запасом.
13
+ */
14
+ export declare const STOP_REQUEST_KEEP_MS: number;
15
+ /**
16
+ * Сколько «Стопов» одного человека помнить (в памяти копии и в хранилище): сверх — уходят его же старые. Чужие записи
17
+ * поток «Стопов» одного человека не вытесняет, таблица не растёт без предела.
18
+ */
19
+ export declare const STOP_REQUESTS_PER_OWNER = 100;
20
+ export interface StopRequests {
21
+ /** Ход запроса `turnRequestId` идёт на этой копии: останавливается, `true`. Иначе — `false`, ничего не меняется. */
22
+ stopRunning(chatId: string, turnRequestId: string): boolean;
23
+ /**
24
+ * Запомнить «Стоп» запроса `turnRequestId`, чей ход ещё не начался или идёт на другой копии: в копии и в хранилище.
25
+ * Ход остановится, когда начнётся или сверится с хранилищем.
26
+ */
27
+ remember(ownerId: string, chatId: string, turnRequestId: string): Promise<void>;
28
+ /**
29
+ * Ход запроса `turnRequestId` начался: `abort` — когда пришёл его «Стоп» (уже пришедший — сразу). Слежка идёт до
30
+ * вызова возвращённой функции.
31
+ */
32
+ watch(chatId: string, turnRequestId: string, abort: () => void): () => void;
33
+ }
34
+ export declare function createStopRequests(input: {
35
+ storage: ChatStorage;
36
+ now: () => Date;
37
+ logError: (message: string, error?: unknown) => void;
38
+ }): StopRequests;
@@ -265,6 +265,20 @@ export interface ChatStorage {
265
265
  }): Promise<boolean>;
266
266
  /** Снять запись пачки чата, если она всё ещё о сообщении `messageId`; о другом сообщении или нет — тихо ничего. */
267
267
  removePendingBurst?(chatId: string, messageId: string): Promise<void>;
268
+ /**
269
+ * «Стоп» хода, начатого запросом `turnRequestId` (id запроса хода от клиента, `TurnRequestContext.turnRequestId`):
270
+ * запрос остановки пришёл раньше, чем ход начался, или на другую копию сервера. Ход этого запроса остановится, на какой
271
+ * бы копии ни начался. Повтор той же записи — тихо ничего. Заодно снимает истёкшие записи (`expiresAt` не позже
272
+ * `stoppedAt`), а у человека `ownerId` оставляет не больше `keepPerOwner` живых: сверх — уходят его же записи с самым
273
+ * ранним `expiresAt`. Чужие записи не трогает. Удаление чата снимает записи чата.
274
+ *
275
+ * Необязательный (вместе с `hasStopRequest`): без него такой «Стоп» действует только внутри копии, которая его приняла.
276
+ */
277
+ saveStopRequest?(request: StoredStopRequest, limits: {
278
+ keepPerOwner: number;
279
+ }): Promise<void>;
280
+ /** Есть ли «Стоп» хода запроса `turnRequestId` в чате `chatId`. */
281
+ hasStopRequest?(chatId: string, turnRequestId: string): Promise<boolean>;
268
282
  /** Новая запись сжатия. Записи только добавляются; сообщения не меняются. Повтор id — ошибка. */
269
283
  insertCompaction(record: StoredCompaction): Promise<void>;
270
284
  /** Записи сжатия чата в порядке добавления. */
@@ -446,5 +460,16 @@ export interface StoredPendingBurst {
446
460
  /** Страница хода (`SendMessageOptions.page`): ход после перезапуска идёт с ней. */
447
461
  page?: TurnRequestContext;
448
462
  }
463
+ /** «Стоп» хода по id его запроса (`ChatStorage.saveStopRequest`). Время — ISO 8601 по часам службы. */
464
+ export interface StoredStopRequest {
465
+ /** Владелец чата: по нему предел записей одного человека. */
466
+ ownerId: string;
467
+ chatId: string;
468
+ turnRequestId: string;
469
+ /** Когда «Стоп» принят. */
470
+ stoppedAt: string;
471
+ /** До какого времени запись нужна: позже ход этого запроса уже не начнётся. */
472
+ expiresAt: string;
473
+ }
449
474
  /** Совместимо со старыми хранилищами приложения; встроенные выполняют один LIMIT 1 без parts. Не проверяет владельца. */
450
475
  export declare function hasChatMessages(storage: ChatStorage, chatId: string): Promise<boolean>;
@@ -38,6 +38,8 @@ export declare function describeChatStorageContract(createStorage: () => ChatSto
38
38
  * `removePendingBurst`) обязаны быть.
39
39
  */
40
40
  pendingBursts?: "required";
41
+ /** `stopRequests: "required"` — «Стоп» по id запроса хода (`saveStopRequest`, `hasStopRequest`) обязан быть. */
42
+ stopRequests?: "required";
41
43
  /** `finishedPartsReplace: "required"` — замена частей готового сообщения (`replaceFinishedMessageParts`) обязана быть. */
42
44
  finishedPartsReplace?: "required";
43
45
  /** `finishWithUsage: "required"` — `finishMessage` пишет `usageRecords` одной транзакцией с ответом (`finishesWithUsage`). */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ykurilov/agent-chat-core",
3
- "version": "0.107.2",
3
+ "version": "0.109.0",
4
4
  "license": "MIT",
5
5
  "type": "module",
6
6
  "sideEffects": false,