@ykurilov/agent-chat-core 0.63.2 → 0.64.0

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

@@ -7,18 +7,22 @@ import type { Chat } from "../conversation/types.js";
  * `metadata: { showOnScreen: true }` и вызовы с запросом подтверждения видны всегда. Запрет `reasoning` и `toolDetails` прячет их из истории и потока, модель и
  * хранилище получают всё. `steer` — поправка к идущему ответу (`POST …/steer`). `modelDetails` — модель, провайдер,
  * уровень рассуждений, расход токенов, метаданные поставщика, владелец чата и текст сводок сжатия в истории и потоке;
- * запрет выключает и `modelChoice`: выбирать невидимую модель нельзя.
+ * запрет выключает и `modelChoice`: выбирать невидимую модель нельзя. `errorDetails` — подробности сбоя провайдера
+ * (провайдер, модель, код, причина, когда снимут предел) в истории и потоке; единственное право, выключенное по
+ * умолчанию: подробности видны любому через инструменты разработчика, открывать их — только админу. При
+ * `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";
 /**
- * Права, как их отдаёт `resolveChatCapabilities`. `modelDetails` в типе необязательно (нет — `true`): свой литерал прав,
- * собранный до этого права, остаётся верным. Ядро и история заполняют его всегда.
+ * Права, как их отдаёт `resolveChatCapabilities`. `modelDetails` (нет — `true`) и `errorDetails` (нет — `false`) в типе
+ * необязательны: свой литерал прав, собранный до этих прав, остаётся верным. Ядро и история заполняют их всегда.
  */
-export type ChatCapabilities = Record<Exclude<ChatCapability, "modelDetails">, boolean> & {
+export type ChatCapabilities = Record<Exclude<ChatCapability, "modelDetails" | "errorDetails">, boolean> & {
     modelDetails?: boolean;
+    errorDetails?: boolean;
 };
 /**
- * Права в чате от приложения: частичный список, пропущенное — `true`. Тот же вход, что у `beforeTurn` (чат с данными
+ * Права в чате от приложения: частичный список, пропущенное — `true` (`errorDetails` — `false`). Тот же вход, что у `beforeTurn` (чат с данными
  * объекта). Не булево значение, неизвестное право или исключение — ошибка приложения.
  */
 export type ChatCapabilitiesHandler = (input: {
@@ -27,8 +31,8 @@ export type ChatCapabilitiesHandler = (input: {
 }) => Partial<ChatCapabilities> | void | Promise<Partial<ChatCapabilities> | void>;
 export declare const CHAT_CAPABILITIES: readonly ChatCapability[];
 /**
- * Все права разрешены и дополнены ответом приложения; `modelDetails: false` выключает и `modelChoice`. Не булево значение
- * или неизвестное право — `TypeError`.
+ * Все права, кроме `errorDetails`, разрешены и дополнены ответом приложения; `modelDetails: false` выключает и
+ * `modelChoice`, и `errorDetails`. Не булево значение или неизвестное право — `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/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";

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.64.0",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,