@ykurilov/agent-chat-core 0.63.2 → 0.65.0

package/dist/types/access/chat-capabilities.d.ts

@@ -7,18 +7,26 @@ import type { Chat } from "../conversation/types.js";
  * `metadata: { showOnScreen: true }` и вызовы с запросом подтверждения видны всегда. Запрет `reasoning` и `toolDetails` прячет их из истории и потока, модель и
  * хранилище получают всё. `steer` — поправка к идущему ответу (`POST …/steer`). `modelDetails` — модель, провайдер,
  * уровень рассуждений, расход токенов, метаданные поставщика, владелец чата и текст сводок сжатия в истории и потоке;
- * запрет выключает и `modelChoice`: выбирать невидимую модель нельзя.
+ * запрет выключает и `modelChoice`: выбирать невидимую модель нельзя. `errorDetails` — подробности сбоя провайдера
+ * (провайдер, модель, код, причина, когда снимут предел) в истории и потоке; единственное право, выключенное по
+ * умолчанию: подробности видны любому через инструменты разработчика, открывать их — только админу. При
+ * `modelDetails: false` выключено и оно. `appNotices` — служебные пометки приложения (`kind: "app"`: касание после
+ * молчания, срок шага сценария) на экране — без текста для модели, только те, у кого есть проекция для экрана
+ * (`appNoticeViews` службы), и только её данные; тоже выключено по умолчанию: клиент в боевом чате их не видит,
+ * включают в проверке и тестовом чате. При `modelDetails: false` выключено и оно.
  */
-export type ChatCapability = "edit" | "regenerate" | "retry" | "branches" | "modelChoice" | "answerEditing" | "chatList" | "compact" | "attachments" | "voice" | "reasoning" | "toolDetails" | "steer" | "modelDetails";
+export type ChatCapability = "edit" | "regenerate" | "retry" | "branches" | "modelChoice" | "answerEditing" | "chatList" | "compact" | "attachments" | "voice" | "reasoning" | "toolDetails" | "steer" | "modelDetails" | "errorDetails" | "appNotices";
 /**
- * Права, как их отдаёт `resolveChatCapabilities`. `modelDetails` в типе необязательно (нет — `true`): свой литерал прав,
- * собранный до этого права, остаётся верным. Ядро и история заполняют его всегда.
+ * Права, как их отдаёт `resolveChatCapabilities`. `modelDetails` (нет — `true`), `errorDetails` и `appNotices` (нет — `false`) в типе
+ * необязательны: свой литерал прав, собранный до этих прав, остаётся верным. Ядро и история заполняют их всегда.
  */
-export type ChatCapabilities = Record<Exclude<ChatCapability, "modelDetails">, boolean> & {
+export type ChatCapabilities = Record<Exclude<ChatCapability, "modelDetails" | "errorDetails" | "appNotices">, boolean> & {
     modelDetails?: boolean;
+    errorDetails?: boolean;
+    appNotices?: boolean;
 };
 /**
- * Права в чате от приложения: частичный список, пропущенное — `true`. Тот же вход, что у `beforeTurn` (чат с данными
+ * Права в чате от приложения: частичный список, пропущенное — `true` (`errorDetails` и `appNotices` — `false`). Тот же вход, что у `beforeTurn` (чат с данными
  * объекта). Не булево значение, неизвестное право или исключение — ошибка приложения.
  */
 export type ChatCapabilitiesHandler = (input: {
@@ -27,8 +35,8 @@ export type ChatCapabilitiesHandler = (input: {
 }) => Partial<ChatCapabilities> | void | Promise<Partial<ChatCapabilities> | void>;
 export declare const CHAT_CAPABILITIES: readonly ChatCapability[];
 /**
- * Все права разрешены и дополнены ответом приложения; `modelDetails: false` выключает и `modelChoice`. Не булево значение
- * или неизвестное право — `TypeError`.
+ * Все права, кроме `errorDetails` и `appNotices`, разрешены и дополнены ответом приложения; `modelDetails: false` выключает и
+ * `modelChoice`, `errorDetails` и `appNotices`. Не булево значение или неизвестное право — `TypeError`.
  */
 export declare function resolveChatCapabilities(given: Partial<ChatCapabilities> | void | null): Required<ChatCapabilities>;
 /** Действие запрещено правами чата: сервер отвечает 403 `action_forbidden`. */

package/dist/types/access/client-visibility.d.ts

@@ -1,7 +1,7 @@
 import type { UIMessageChunk } from "ai";
 import type { ChatCapabilities } from "./chat-capabilities.js";
 /**
- * Что из ответа видит браузер по правам `reasoning`, `toolDetails` и `modelDetails`. Хранилище, модель и хуки получают
+ * Что из ответа видит браузер по правам `reasoning`, `toolDetails`, `modelDetails` и `errorDetails`. Хранилище, модель и хуки получают
  * ответ целиком: видимость — только на выходе к клиенту (история, поток, повтор кусков после переподключения).
  */
 export interface ClientVisibility {
@@ -38,4 +38,4 @@ export declare const SHOW_ON_SCREEN_KEY = "showOnScreen";
  * Видимость для прав зрителя. При `toolDetails: false` видны вызовы с пометкой `showOnScreen`, инструменты SDK, которым
  * нужен экран (`sdkScreenTool`: виджеты, браузерные), и вызовы, спросившие подтверждения.
  */
-export declare function clientVisibilityOf(capabilities: Pick<ChatCapabilities, "reasoning" | "toolDetails" | "modelDetails">, sdkScreenTool: (toolName: string) => boolean): ClientVisibility;
+export declare function clientVisibilityOf(capabilities: Pick<ChatCapabilities, "reasoning" | "toolDetails" | "modelDetails" | "errorDetails">, sdkScreenTool: (toolName: string) => boolean): ClientVisibility;

package/dist/types/agent-run/run-agent-turn.d.ts

@@ -1,7 +1,7 @@
 import type { ToolSet, UIMessageChunk } from "ai";
 import type { MessageAttachments } from "../attachments/message-attachments.js";
 import type { AgentAudience, AgentChannel, ChatSubject, GroupTurn, UsageSource } from "../conversation/types.js";
-import type { AgentChatMessage, ChatErrorKind, FinalAnswerStatus, TokenUsage } from "../conversation/types.js";
+import type { AgentChatMessage, ChatError, FinalAnswerStatus, TokenUsage } from "../conversation/types.js";
 import type { AgentHelper } from "../helpers/helper-types.js";
 import type { DataChange, ScreenPlace } from "../page-context/page-context.js";
 import type { ModelCatalog, ModelProfile } from "../models/model-catalog.js";
@@ -261,9 +261,7 @@ export interface AgentTurnInput {
         status: FinalAnswerStatus;
         parts: AgentChatMessage["parts"];
         usage: TokenUsage | null;
-        error: {
-            kind: ChatErrorKind;
-        } | null;
+        error: ChatError | null;
         providerId: string;
     }, stopWaiting: AbortSignal) => Promise<AppEvent[]>;
     /** Итог ответа записан в хранилище, до расхода и `afterTurn`: для срока хода, который не должен обрывать хук. */

package/dist/types/app-state/state-messages.d.ts

@@ -38,7 +38,8 @@ export declare function publicAppStateParts<P extends {
 }>(parts: readonly P[], hidden?: HiddenStateKey): P[];
 /**
  * Сообщения для браузера: части без служебных ключей, без застывших блоков контекста, отметки `endTurn` и служебных
- * сообщений вида `app` (они только для модели);
+ * сообщений вида `app` (они только для модели; с `appNoticeViews` — остаются те, у кого есть проекция для экрана: без
+ * текста для модели, `data` — проекция);
  * сообщение человека, у которого не осталось частей, не уходит. Служебное сообщение состояния (`isStateMessage`) перед
  * обычным не показывается: его открытые записи едут в начале этого сообщения, и экран сворачивает то же состояние.
  */
@@ -47,9 +48,16 @@ export declare function publicMessages<M extends {
     parts: ReadonlyArray<{
         type: string;
     }>;
-}>(messages: readonly M[], hidden?: HiddenStateKey): M[];
+}>(messages: readonly M[], hidden?: HiddenStateKey, options?: {
+    appNoticeViews?: AppNoticeViews;
+}): M[];
 /** Кусок потока для браузера: запись состояния без скрытых ключей; ничего не осталось — `undefined`. */
 export declare function publicStateChunk(chunk: UIMessageChunk, hidden?: HiddenStateKey): UIMessageChunk | undefined;
+/**
+ * Проекции пометок приложения для экрана (`appNoticeViews` службы): имя пометки → безопасные для браузера данные из
+ * `data`. Нет проекции, она вернула `undefined` или упала — пометка в браузер не уходит.
+ */
+export type AppNoticeViews = Readonly<Record<string, (data: unknown) => unknown>>;
 /** Части только для модели: застывшие блоки контекста и отметка конца хода инструментом без слов. */
 export declare function isModelOnlyPart(part: {
     type: string;

package/dist/types/chat-service.d.ts

@@ -27,6 +27,7 @@ import type { CompactionSettings } from "./compaction/compaction-settings.js";
 import type { ChatGreeting, ImportChatInput, OpenSubjectChatInput, OpenSubjectChatResult } from "./subject-chats/subject-chats.js";
 import type { AppStateValues } from "./app-state/app-state.js";
 import type { StateChangedHandler } from "./app-state/state-changed.js";
+import type { AppNoticeViews } from "./app-state/state-messages.js";
 import type { BranchFork } from "./conversation/branches.js";
 import type { AnswerEdit } from "./conversation/answer-edit.js";
 import type { ReplyChecksSetting } from "./agent-run/reply-check-types.js";
@@ -454,6 +455,12 @@ export interface ChatServiceOptions {
      * @throws TypeError (при создании службы) неверное имя.
      */
     privateStateKeys?: readonly string[];
+    /**
+     * Проекции пометок приложения (`kind: "app"`) для экрана при праве `appNotices`: имя пометки → безопасные данные
+     * (`(data) => ({ silentMs })`). Пометка без проекции в браузер не уходит, даже с правом. Сценарии (`flow.withChat`)
+     * добавляют свои сами.
+     */
+    appNoticeViews?: AppNoticeViews;
 }
 /** Ход, для которого берётся инструкция чата; у сжатия его нет. */
 export interface ChatInstructionsTurn {

package/dist/types/conversation/types.d.ts

@@ -6,6 +6,23 @@ export declare const CURRENT_FORMAT_VERSION = 1;
 export type AnswerStatus = "streaming" | "complete" | "stopped" | "error" | "interrupted" | "awaiting_approval";
 export type FinalAnswerStatus = Exclude<AnswerStatus, "streaming">;
 export type ChatErrorKind = "overloaded" | "rate_limited" | "insufficient_funds" | "invalid_key" | "context_overflow" | "other";
+/**
+ * Подробности сбоя провайдера для того, кому приложение их открыло (право `errorDetails`): кто не ответил и почему.
+ * `reason` — одна строка до 300 знаков из сообщения провайдера, секреты и параметры адресов вычищены. `resetsAt` — когда
+ * провайдер обещал снять предел (ISO), если сообщил.
+ */
+export interface ChatErrorDetails {
+    providerId: string;
+    modelId: string;
+    statusCode?: number;
+    reason?: string;
+    resetsAt?: string;
+}
+/** Сбой ответа: вид для подписи и, если есть, подробности (хранятся всегда, в браузер — по праву `errorDetails`). */
+export interface ChatError {
+    kind: ChatErrorKind;
+    details?: ChatErrorDetails;
+}
 export interface TokenUsage {
     inputTokens: number;
     cachedInputTokens: number;
@@ -97,9 +114,7 @@ export interface ChatMessageMetadata {
     usage?: TokenUsage;
     reasoningDurationsMs?: Record<string, number>;
     status?: AnswerStatus;
-    error?: {
-        kind: ChatErrorKind;
-    };
+    error?: ChatError;
     /** Есть, если озвучку ответа оборвало перебивание. */
     voiceCut?: VoiceCut;
     /** Ответ не дошёл до человека (`markUndelivered`): модель его не видит, экран подписывает «не доставлено». */
@@ -118,9 +133,7 @@ export interface StoredMessage {
     providerId: string | null;
     usage: TokenUsage | null;
     reasoningDurationsMs: Record<string, number>;
-    error: {
-        kind: ChatErrorKind;
-    } | null;
+    error: ChatError | null;
     /**
      * Отметка обрыва озвучки. Необязательное поле: старые данные и хранилища без голосового режима его не знают;
      * встроенные хранилища читают отсутствие как `null`.

package/dist/types/index.d.ts

@@ -1,5 +1,5 @@
 export { BUILT_IN_USAGE_SOURCES, CURRENT_FORMAT_VERSION } from "./conversation/types.js";
-export type { AfterTurnState, AgentAudience, AgentChannel, AgentChatMessage, AnswerAliveMark, AnswerStatus, Chat, ChatErrorKind, ChatMessageMetadata, ChatSubject, ExternalChannel, FinalAnswerStatus, GroupTurn, PendingStepUsage, StoredBranchSelection, StoredCompaction, StoredMessage, TokenUsage, UsageByChatFilter, UsageChatSum, UsageFilter, UsageRecord, UsageSource, BuiltInUsageSource, UsageSum, VoiceCut, } from "./conversation/types.js";
+export type { AfterTurnState, AgentAudience, AgentChannel, AgentChatMessage, AnswerAliveMark, AnswerStatus, Chat, ChatError, ChatErrorDetails, ChatErrorKind, ChatMessageMetadata, ChatSubject, ExternalChannel, FinalAnswerStatus, GroupTurn, PendingStepUsage, StoredBranchSelection, StoredCompaction, StoredMessage, TokenUsage, UsageByChatFilter, UsageChatSum, UsageFilter, UsageRecord, UsageSource, BuiltInUsageSource, UsageSum, VoiceCut, } from "./conversation/types.js";
 export type { AgentHelper, HelperPendingApproval, HelperProgress, HelperStep, HelperStepReport, RunHelper, RunHelperInput, RunHelperResult, } from "./helpers/helper-types.js";
 export { runHelper } from "./helpers/run-helper.js";
 export { AGENT_NOTICE_PART_TYPE } from "./notices/agent-notice.js";
@@ -60,6 +60,7 @@ export { accessRefusedResponse, allowedUser } from "./access/resolved-user.js";
 export type { AccessRefusal, ResolvedUser } from "./access/resolved-user.js";
 export { ActionForbiddenError, CHAT_CAPABILITIES, resolveChatCapabilities } from "./access/chat-capabilities.js";
 export type { ChatCapabilities, ChatCapabilitiesHandler, ChatCapability } from "./access/chat-capabilities.js";
+export type { AppNoticeViews } from "./app-state/state-messages.js";
 export { CHAT_CLOSED_PART_TYPE, ChatClosedError, normalizeChatClosure } from "./access/chat-closure.js";
 export type { ChatClosure } from "./access/chat-closure.js";
 export { ChatCreationRefusedError } from "./access/chat-creation.js";

package/dist/types/provider-errors/provider-error-details.d.ts

@@ -0,0 +1,18 @@
+import type { ChatErrorDetails } from "../conversation/types.js";
+import type { ModelCatalog } from "../models/model-catalog.js";
+export interface ProviderErrorDetailsContext {
+    providerId: string;
+    modelId: string;
+    /** Окружение сервера: значения ключей провайдеров вычищаются из причины. */
+    env: Record<string, string | undefined>;
+    catalog: ModelCatalog;
+    /** Часы хода, мс: «через N секунд» и проверка, что дата обнуления в будущем. По умолчанию — сейчас. */
+    now?: () => number;
+}
+/**
+ * Подробности сбоя для админа: провайдер, модель, код, причина одной строкой (сообщение провайдера из тела ответа, без
+ * секретов и параметров адресов) и когда провайдер снимет предел — из метаданных (`limit_reset`, `resets_at`) или
+ * текста сообщения о пределе («Key limit exceeded … resets 2026-11-01»). Дата принимается только в будущем и не дальше
+ * двух лет; время без пояса — UTC.
+ */
+export declare function providerErrorDetails(error: unknown, context: ProviderErrorDetailsContext): ChatErrorDetails;

package/dist/types/text/scrub-secrets.d.ts

@@ -4,7 +4,9 @@ export declare const MIN_SECRET_LENGTH = 8;
 /**
  * Вычищает секреты из текста, который уходит человеку, в базу, в журнал или модели: известные значения
  * (`knownSecrets`, например ключи провайдеров из окружения), пароль в адресе `схема://логин:пароль@`,
- * заголовок `Authorization`, `?key=…`, поля вроде `password=…`, `password: …` и `"token": "…"`, узнаваемые ключи сервисов.
+ * заголовок `Authorization`, `Bearer …` в любом регистре, `key=…`, поля вроде `password=…`, `password: …` и `"token": "…"`,
+ * слово ключа через пробел перед похожим на секрет значением (`token abc123def456`), узнаваемые ключи сервисов и их
+ * маски со звёздочками.
  */
 export declare function scrubSecrets(text: string, knownSecrets?: Iterable<string | undefined>): string;
 /**

package/dist/types/turn-hooks/turn-hooks.d.ts

@@ -1,4 +1,4 @@
-import type { AgentChannel, Chat, ChatErrorKind, ChatSubject, FinalAnswerStatus, StoredMessage, TokenUsage } from "../conversation/types.js";
+import type { AgentChannel, Chat, ChatError, ChatSubject, FinalAnswerStatus, StoredMessage, TokenUsage } from "../conversation/types.js";
 /** Что человек делает с чатом, когда приложение решает, пускать ли ход. */
 export type TurnAction = "send" | "edit" | "retry" | "regenerate" | "approval" | "widget" | "notice";
 /** Отказ приложения в ходе: код для программы, текст для человека. */
@@ -130,9 +130,8 @@ export interface TurnResult {
     usage: TokenUsage | null;
     /** Цена хода в долларах; `null` — у модели нет цены. */
     costUsd: number | null;
-    error?: {
-        kind: ChatErrorKind;
-    };
+    /** Вид сбоя и подробности провайдера (`details`): хук на сервере получает их всегда. */
+    error?: ChatError;
     /**
      * Каким действием начат ход (см. `TurnAction`). `null` — итог доделан после перезапуска (`recovered`), а ядро не
      * помнит действие; ход по служебному сообщению и тогда — `notice`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ykurilov/agent-chat-core",
-  "version": "0.63.2",
+  "version": "0.65.0",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,