@ykurilov/agent-chat-core 0.105.1 → 0.106.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.
@@ -19,7 +19,7 @@ export interface StateChangedInput {
19
19
  }
20
20
  /**
21
21
  * Хук смены состояния чата: копия состояния в таблицах приложения. Повтор с тем же состоянием ничего не должен ломать —
22
- * сводите копию полной заменой. Бросок или отказ — повтор.
22
+ * сводите копию полной заменой. Бросок или отказ — повтор. Состояние, которое к попытке уже сменилось, не доставляется.
23
23
  */
24
24
  export type StateChangedHandler = (input: StateChangedInput) => void | Promise<void>;
25
25
  /** Срок хука смены состояния по умолчанию: все попытки и паузы, мс. */
@@ -50,6 +50,11 @@ export declare function createStateChanged(context: {
50
50
  attempts?: number;
51
51
  chatEvents: ChatEvents;
52
52
  logError: (message: string, error?: unknown) => void;
53
+ /**
54
+ * Состояние чата в хранилище сейчас. Перед каждой попыткой хука: состояние уже другое (его сменила другая копия
55
+ * сервера или следующий ход) — хук не зовётся, новое разошлёт тот, кто его записал.
56
+ */
57
+ currentState?: (chatId: string) => Promise<AppStateValues>;
53
58
  }): StateChanged;
54
59
  type StateChangedFailure = {
55
60
  reason: string;
@@ -80,6 +80,17 @@ export type ChatEvent = {
80
80
  chatId: string;
81
81
  messageId: string;
82
82
  }
83
+ /**
84
+ * Человек выбрал другую ветку на развилке (`selectBranch`): `messageId` — выбранное сообщение. Другой вкладке пора
85
+ * перечитать историю, иначе она дописывает в прежнюю ветку. Выбор уже текущей ветки события не даёт. Клиенты до 0.106
86
+ * такое событие пропускают и видят выбранную ветку при следующем чтении истории.
87
+ */
88
+ | {
89
+ type: "branch-selected";
90
+ ownerId: string;
91
+ chatId: string;
92
+ messageId: string;
93
+ }
83
94
  /**
84
95
  * Данные чата изменены (`service.updateChatData`). Самих данных в событии нет, вкладке оно не пересылается: данные
85
96
  * чата остаются на сервере. Новое значение видят инструменты и хуки со следующего хода.
@@ -1,4 +1,4 @@
1
- /** Настройки сжатия истории; всё необязательно, значения по умолчанию — из решений Юрия. */
1
+ /** Настройки сжатия истории; всё необязательно, значения по умолчанию подобраны в SDK. */
2
2
  export interface CompactionSettings {
3
3
  /** С какого размера контекста сжимать (токены провайдера). Для малых окон порог не выше 80% окна. */
4
4
  thresholdTokens?: number;
@@ -24,6 +24,8 @@ export interface ResolvedCompactionSettings extends CompactionSettings {
24
24
  }
25
25
  /** Настройки с значениями по умолчанию; `false` выключает сжатие (`null`). */
26
26
  export declare function resolveCompactionSettings(setting: CompactionSettings | false | undefined): ResolvedCompactionSettings | null;
27
+ /** Хвост и потолок сводки для окна модели чата: в малом окне (32 тыс. токенов) они вместе не уместились бы и пропорционально ужимаются. */
28
+ export declare function settingsForWindow(settings: ResolvedCompactionSettings, contextWindowTokens: number): ResolvedCompactionSettings;
27
29
  /** Порог для выбранной модели: не выше 80% её окна. */
28
30
  export declare function effectiveThreshold(settings: ResolvedCompactionSettings, contextWindowTokens: number): number;
29
31
  /** Контекст у предела окна: новый ответ должен дождаться сжатия. */
@@ -29,6 +29,7 @@ export { cachePriceWarnings, modelAcceptsImages } from "./models/model-catalog.j
29
29
  export { modelMaySeeToolResultImages, toolImageFallbackText } from "./agent-run/tool-result-images-policy.js";
30
30
  export type { CacheTtl, GenerationUsage, ModelCatalog, ModelPrice, ModelPriceRates, ModelPriceTier, ModelProfile, ModelSampling, ProviderConnection, ProviderConnectionOptions, ProviderDescription, ProviderOptionsByProvider, ProviderRequestOptions, ReasoningLevelId, ReasoningRequest, } from "./models/model-catalog.js";
31
31
  export type { LongTermMemory, MemoryError, MemoryErrorKind, MemoryNote, MemoryNoteInput, MemoryRevertGuard, MemoryWriteGuard } from "./memory/long-term-memory.js";
32
+ export { assertWellFormedMemoryNote } from "./memory/long-term-memory.js";
32
33
  export type { MemoryMergeApplyResult, MemoryMergeGroup, MemoryMergeInput, MemoryMergeRevertResult, MemoryOptimizationOutcome, MemoryOptimizationRules, MemoryOptimizationRun, MemoryOptimizationStatus, MergedMemoryNote, OptimizationRunTiming, } from "./memory/memory-optimization.js";
33
34
  export { isOptimizationBlocked, pauseAfterFailure, revertRefusal } from "./memory/memory-optimization.js";
34
35
  export { costOfUsage } from "./usage/usage-cost.js";
@@ -75,7 +76,7 @@ export type { ChatClosure } from "./access/chat-closure.js";
75
76
  export { ChatCreationRefusedError } from "./access/chat-creation.js";
76
77
  export type { BeforeCreateChatHandler, ChatCreationRefusal } from "./access/chat-creation.js";
77
78
  export { DEFAULT_MAX_CONCURRENT_TURNS_PER_USER, TooManyTurnsError } from "./running-answers/turn-slots.js";
78
- export type { SpendingLimits, SpendingPeriod, SpendingRefusalReason, SpendingScope, SpendingState, SpendingStatus, SpendingUnit, SpendingWindowStatus, TurnSpendingRules, } from "./spending/spending-limits.js";
79
+ export type { CountedMessageSlot, SpendingLimits, SpendingPeriod, SpendingRefusalReason, SpendingScope, SpendingState, SpendingStatus, SpendingUnit, SpendingWindowStatus, TurnSpendingRules, } from "./spending/spending-limits.js";
79
80
  export { createRequestOriginCheck, isSafeMethod, originRefusalHint } from "./request-origin/request-origin.js";
80
81
  export type { OriginRefusal, RequestOriginCheck, RequestOriginCheckOptions } from "./request-origin/request-origin.js";
81
82
  export { createInMemoryChatStorage } from "./storage/in-memory-storage.js";
@@ -8,6 +8,8 @@ export interface MemoryNoteInput {
8
8
  categories: string[];
9
9
  content: string;
10
10
  }
11
+ /** Как база с NOT NULL: разделы — список строк, текст — строка. Хранилища проверяют вход этим до записи. */
12
+ export declare function assertWellFormedMemoryNote(note: MemoryNoteInput): void;
11
13
  /** Запись памяти. Владелец (`ownerId`) — свойство хранилища и наружу не выдаётся. */
12
14
  export interface MemoryNote extends MemoryNoteInput {
13
15
  /** Выдаёт хранилище, уникален. */
@@ -180,7 +180,7 @@ export interface ProviderConnectionOptions {
180
180
  * Через него идут все запросы провайдера: ход, фоновые вызовы памяти и сжатия, сверка расхода.
181
181
  */
182
182
  export interface ProviderConnection {
183
- /** Адрес API вместо стандартного, `http(s)://…`, например `https://fr-api-route.yeycourses.com/openrouter/api/v1`. */
183
+ /** Адрес API вместо стандартного, `http(s)://…`, например `https://proxy.example.com/openrouter/api/v1`. */
184
184
  baseURL?: string;
185
185
  /** Заголовки к каждому запросу, например `{ "X-Proxy-Token": process.env.PROXY_TOKEN }`. Значения — секреты: вычищаются из ошибок и журналов. */
186
186
  headers?: Record<string, string>;
@@ -71,6 +71,10 @@ export interface TurnSpendingRules {
71
71
  /** Потолок вызовов инструментов за ход. */
72
72
  maxToolCalls?: number;
73
73
  }
74
+ /** Место под сообщение в окнах сообщений: вызов отдаёт его назад, `confirm` — сообщение записано, место за ним. */
75
+ export type CountedMessageSlot = (() => Promise<void>) & {
76
+ confirm?: () => Promise<void>;
77
+ };
74
78
  /**
75
79
  * Лимиты расходов (расширение `@ykurilov/agent-chat-limits`). Ядро зовёт проверку до начала хода и ничего не знает
76
80
  * о деньгах: токены оно только записывает в журнал расхода.
@@ -114,11 +118,14 @@ export interface SpendingLimits {
114
118
  * Счёт сообщений: служба чата зовёт его при отправке и правке сообщения человека, после проверки хода и до записи.
115
119
  * Окно сообщений исчерпано — `SpendingLimitReachedError` с `unit: "messages"`. Нет метода — сообщения не считаются.
116
120
  * Возвращает, как отдать место назад: служба зовёт это, если сообщение так и не записалось. Нечего отдавать — `undefined`.
121
+ * У возврата может быть `confirm`: служба зовёт его, когда сообщение `messageId` записано. Неподтверждённое место
122
+ * лимиты вправе вернуть сами, если сообщения так и нет (процесс упал между местом и записью).
117
123
  */
118
124
  takeMessage?(input: {
119
125
  userId: string;
120
126
  chatId: string;
121
- }): Promise<(() => Promise<void>) | undefined>;
127
+ messageId?: string;
128
+ }): Promise<CountedMessageSlot | undefined>;
122
129
  /**
123
130
  * Чат удалён: лимиты стирают то, что хранили про этот чат (окна области `chat`). Расход в журнале остаётся.
124
131
  * Ошибка удаление не отменяет — чата уже нет — и уходит в журнал сервера.
@@ -18,12 +18,14 @@ export interface ChatTurnWriteGuard {
18
18
  export type StreamingMessagePatch = Pick<StoredMessage, "parts"> & Partial<Pick<StoredMessage, "usage" | "reasoningDurationsMs" | "alive">> & ChatTurnWriteGuard;
19
19
  /**
20
20
  * `providerId` — только если ответил запасной провайдер, а не выбранный при вставке. `afterTurn` — состояние хука итога
21
- * (обычно `pending`), ставится той же записью; хранилище без состояния хука его пропускает.
21
+ * (обычно `pending`), ставится той же записью; хранилище без состояния хука его пропускает. `usageRecords` — записи
22
+ * расхода хода: хранилище с `finishesWithUsage` пишет их одной транзакцией с ответом, без него ядро их не передаёт.
22
23
  */
23
24
  export type FinishedMessagePatch = {
24
25
  status: FinalAnswerStatus;
25
26
  } & Partial<Pick<StoredMessage, "parts" | "usage" | "reasoningDurationsMs" | "error" | "providerId">> & {
26
27
  afterTurn?: AfterTurnState;
28
+ usageRecords?: readonly UsageRecord[];
27
29
  } & ChatTurnWriteGuard;
28
30
  /** Новый чат. `createdAt` задан — и создание, и обновление чата получают эту дату; нет — время записи. */
29
31
  export interface NewChatInput {
@@ -84,6 +86,11 @@ export interface MessagePartsLink extends MessageLink {
84
86
  export interface ChatStorage {
85
87
  /** Адаптер атомарно исполняет ChatTurnWriteGuard у всех записей ответа; обязателен при наличии аренд. */
86
88
  readonly guardedTurnWrites?: true;
89
+ /**
90
+ * `finishMessage` пишет `usageRecords` той же транзакцией, что и конечный ответ: сбой или падение процесса между
91
+ * ними не теряют расход законченного ответа. Без флага ядро пишет расход отдельной записью после ответа.
92
+ */
93
+ readonly finishesWithUsage?: true;
87
94
  /** Повтор `subjectKey` у того же владельца — `DuplicateChatSubjectError`, чат не записан. */
88
95
  createChat(input: NewChatInput): Promise<Chat>;
89
96
  getChat(chatId: string): Promise<Chat | null>;
@@ -40,4 +40,6 @@ export declare function describeChatStorageContract(createStorage: () => ChatSto
40
40
  pendingBursts?: "required";
41
41
  /** `finishedPartsReplace: "required"` — замена частей готового сообщения (`replaceFinishedMessageParts`) обязана быть. */
42
42
  finishedPartsReplace?: "required";
43
+ /** `finishWithUsage: "required"` — `finishMessage` пишет `usageRecords` одной транзакцией с ответом (`finishesWithUsage`). */
44
+ finishWithUsage?: "required";
43
45
  }): void;
@@ -1,4 +1,4 @@
1
- import type { TokenUsage, UsageSource, UsageSum } from "../conversation/types.js";
1
+ import type { TokenUsage, UsageRecord, UsageSource, UsageSum } from "../conversation/types.js";
2
2
  import type { ModelCatalog } from "../models/model-catalog.js";
3
3
  import type { ChatStorage } from "../storage/chat-storage.js";
4
4
  export interface SpentTokens {
@@ -25,6 +25,8 @@ export interface SpentTokens {
25
25
  * Нулевой расход не пишется (`null`), сбой записи не бросается: он уходит в журнал сервера (`null`).
26
26
  */
27
27
  export declare function recordSpentTokens(input: SpentTokens): Promise<string | null>;
28
+ /** Запись расхода со стоимостью, как её пишет `recordSpentTokens`; нулевой расход — `null`. */
29
+ export declare function usageRecordOf(input: Omit<SpentTokens, "storage" | "logError">): UsageRecord | null;
28
30
  /** Цена по шагам (час пик — по времени шага, без него — по началу хода) или всего расхода как одного запроса. */
29
31
  export declare function costOfSpent({ catalog, modelId, providerId, spent, steps, startedAt }: Pick<SpentTokens, "catalog" | "modelId" | "providerId" | "spent" | "steps" | "startedAt">): number;
30
32
  type UsageField = "inputTokens" | "cachedInputTokens" | "cacheWriteTokens" | "outputTokens" | "reasoningTokens";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ykurilov/agent-chat-core",
3
- "version": "0.105.1",
3
+ "version": "0.106.0",
4
4
  "license": "MIT",
5
5
  "type": "module",
6
6
  "sideEffects": false,