@ykurilov/agent-chat-react 0.0.0-stage → 0.55.0

package/dist/types/background-tasks/use-background-tasks.d.ts

@@ -0,0 +1,53 @@
+import type { TaskStatusView } from "../skin-contract.js";
+/** Задача, как её отдаёт `GET {chat}/tasks`. */
+export interface BackgroundTask {
+    id: string;
+    title: string;
+    kind: string;
+    name: string;
+    status: TaskStatusView;
+    startedAt: string;
+    finishedAt?: string;
+    progress?: unknown;
+}
+/** Решение человека по задаче, которая ждёт подтверждения. */
+export type TaskApprovalDecision = "allow" | "deny";
+export type TaskDecisionState = {
+    state: "pending";
+} | {
+    state: "failed";
+} | {
+    state: "decided";
+    decision: TaskApprovalDecision;
+};
+export interface UseBackgroundTasksOptions {
+    /** Адрес чата: `{api}/{chatId}`. */
+    chatUrl: string;
+    /** Скин показывает карточки или плашки, история загружена. Нет — задачи не запрашиваются. */
+    enabled: boolean;
+    /** Растёт, когда список мог измениться (подписка открылась, пришло `tasks-changed`): список перечитывается. */
+    version: number;
+    fetch?: (url: string, init?: RequestInit) => Promise<Response>;
+}
+export interface BackgroundTasks {
+    /** Задачи чата; пусто, пока не загружены или у сервера фона нет. */
+    tasks: readonly BackgroundTask[];
+    /** Текущее время для «сколько идёт»: тикает раз в секунду, пока есть живые задачи. */
+    now: number;
+    cancel: (taskId: string) => Promise<void>;
+    cancelingIds: ReadonlySet<string>;
+    /** Ответ на вопрос `approvalId` задачи: ответ на вопрос, который задача уже не задаёт, сервер не примет. */
+    decide: (taskId: string, approvalId: string, decision: TaskApprovalDecision) => Promise<void>;
+    /** Решения по номеру вопроса: у одной задачи вопросов бывает несколько. */
+    decisions: Readonly<Record<string, TaskDecisionState>>;
+}
+export declare const isLiveTask: (task: BackgroundTask) => boolean;
+/** Номер вопроса, ответа на который задача ждёт сейчас (`progress.pendingApproval.approvalId`). */
+export declare function pendingApprovalIdOf(task: BackgroundTask): string | undefined;
+/** Сколько идёт (или шла) задача к моменту `now`. */
+export declare function taskElapsedMs(task: BackgroundTask, now: number): number;
+/**
+ * Фоновые задачи чата: список с сервера, отмена и решение по подтверждению. Сервер без фона (404) — задач нет,
+ * повторных запросов тоже.
+ */
+export declare function useBackgroundTasks({ chatUrl, enabled, version, fetch: customFetch }: UseBackgroundTasksOptions): BackgroundTasks;

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

@@ -0,0 +1,33 @@
+/**
+ * Права человека в чате и закрытие чата — копия договора ядра (`ChatCapabilities`, `ChatClosure`): пакет экрана от
+ * ядра не зависит. Права приходят с историей (`capabilities`), закрытие — в `chat.closed` истории, в отказе 409
+ * `chat_closed`, куском потока `data-chat-closed` и событиями наблюдения `chat-closed`/`chat-reopened`.
+ */
+export type ChatCapability = "edit" | "regenerate" | "retry" | "branches" | "modelChoice" | "answerEditing" | "chatList" | "compact" | "attachments" | "voice" | "reasoning" | "toolDetails" | "steer" | "modelDetails";
+/**
+ * `modelDetails` — модель, провайдер, расход и владелец в истории и потоке; запрет выключает и выбор модели, меню моделей
+ * экран тогда не спрашивает. В типе необязательно (нет — `true`): свой литерал прав без него остаётся верным.
+ */
+export type ChatCapabilities = Record<Exclude<ChatCapability, "modelDetails">, boolean> & {
+    modelDetails?: boolean;
+};
+/** Почему чат закрыт: код для программы, текст для человека. */
+export interface ChatClosure {
+    code: string;
+    message: string;
+}
+/** Что можно в открытом чате и закрыт ли он. */
+export interface ChatAccess {
+    capabilities: ChatCapabilities;
+    /** `null` — чат открыт. */
+    closed: ChatClosure | null;
+}
+/** Транзитный кусок потока ответа: инструмент закрыл чат. */
+export declare const CHAT_CLOSED_PART_TYPE = "data-chat-closed";
+/** Всё разрешено: сервер до 0.27 прав не присылает. */
+export declare const ALL_CAPABILITIES: Required<ChatCapabilities>;
+/** Права из ответа сервера: пропущенное и не булево — разрешено. */
+export declare function capabilitiesOf(value: unknown): Required<ChatCapabilities>;
+/** Закрытие из ответа сервера; `null` — нет или неверной формы. */
+export declare function closureOf(value: unknown): ChatClosure | null;
+export declare function sameCapabilities(a: ChatCapabilities, b: ChatCapabilities): boolean;

package/dist/types/chat-list/active-chat-memory.d.ts

@@ -0,0 +1,5 @@
+/** Ключ, под которым запоминается открытый чат, если приложение не задало свой. */
+export declare const defaultRememberKey: (api: string) => string;
+/** Чат, открытый в прошлый раз в этом браузере (под этим ключом). Хранилище недоступно или пусто — `null`. */
+export declare function readRememberedChat(key: string): string | null;
+export declare function rememberChat(key: string, chatId: string): void;

package/dist/types/chat-list/chat-list-client.d.ts

@@ -0,0 +1,35 @@
+import type { AppRefusal } from "../app-refusal.js";
+import type { ChatClosure } from "../chat-access.js";
+/** Строка списка чатов, как её отдаёт сервер (`GET {api}`). */
+export interface ChatListEntry {
+    id: string;
+    /** `null` — у чата ещё нет названия. */
+    title: string | null;
+    createdAt: string;
+    updatedAt: string;
+    /** Мессенджер, из которого создан чат; нет — чат из веба. */
+    origin?: string;
+    /** Ключ объекта приложения (урок, заказ): есть у чатов объектов, когда сервер их показывает (`chatList.subjectChats`). */
+    subjectKey?: string;
+    /** Чат закрыт (`closeChat`): причина кодом и словами; у открытого чата поля нет. Форму проверяет слой поведения. */
+    closed?: ChatClosure;
+}
+type Fetch = typeof globalThis.fetch;
+/** Сервер ответил отказом; `status` — код ответа. */
+export declare class ChatListRequestError extends Error {
+    readonly status: number;
+    constructor(status: number, action: string);
+}
+/** Приложение не дало создать чат (`403 { error: { kind: "chat_creation_refused", code, message } }`). */
+export declare class ChatCreationRefusedError extends Error {
+    readonly refusal: AppRefusal;
+    constructor(refusal: AppRefusal);
+}
+export declare function fetchChatList(api: string, fetchImpl: Fetch): Promise<ChatListEntry[]>;
+/** Создаёт пустой чат; возвращает его id. */
+export declare function createChatOnServer(api: string, fetchImpl: Fetch): Promise<string>;
+/** Возвращает название, как оно записано на сервере. */
+export declare function renameChatOnServer(api: string, fetchImpl: Fetch, chatId: string, title: string): Promise<string>;
+/** Удаляет чат. Чата уже нет (404) — это тоже успех: человек хотел, чтобы его не было. */
+export declare function deleteChatOnServer(api: string, fetchImpl: Fetch, chatId: string): Promise<void>;
+export {};

package/dist/types/chat-list/chat-list-skin.d.ts

@@ -0,0 +1,63 @@
+import type { ChatClosure } from "../chat-access.js";
+import type { ChatOriginView } from "../skin-contract.js";
+import type { ComponentType, ReactNode } from "react";
+/** Строка списка чатов для скина. */
+export interface ChatListItemView {
+    id: string;
+    /** `null` — у чата ещё нет названия: скин показывает надпись `chatListUntitled`, а в поле переименования ставит пустую строку. */
+    title: string | null;
+    /** Этот чат открыт. */
+    active: boolean;
+    /** Чат создан из мессенджера (версия 18): скин ставит пометку. Нет — чат из веба. */
+    origin?: ChatOriginView;
+    /** Чат закрыт: скин ставит пометку `chatListClosed`, причину (`message`) — подсказкой. Нет — чат открыт. */
+    closed?: ChatClosure;
+}
+/** Окно подтверждения удаления. Удалить чат можно только через `onConfirm`. */
+export interface ChatListDeleteRequestView {
+    /** Название удаляемого чата. */
+    title: string;
+    /** Запрос на удаление ушёл, ждём ответа. */
+    pending: boolean;
+    onConfirm: () => void;
+    onCancel: () => void;
+}
+/**
+ * Договор скина, версия 7 (расширение «список чатов»; договор чата `ChatSkin` не менялся): только для `ChatWorkspace`.
+ * Слой поведения решает, что показать и когда что-то удалять; скин рисует. Надписи компоненты берут из `useChatLabels()`.
+ */
+export interface ChatListSkin {
+    /**
+     * Каркас: список чатов и открытый чат. На широком экране список рядом с чатом; на узком — выезжающая панель
+     * (открыта при `listOpen`), а название открытого чата и кнопка «Чаты» всегда на виду.
+     */
+    ChatWorkspace: ComponentType<{
+        /** Нет (версия 20) — у открытого чата запрещено право `chatList`: списка и кнопки «Чаты» не рисовать, только чат. */
+        list?: ReactNode;
+        /** Открытый чат. */
+        children: ReactNode;
+        /** Название открытого чата для узкого экрана. */
+        activeTitle: string;
+        listOpen: boolean;
+        onListOpenChange: (open: boolean) => void;
+    }>;
+    ChatList: ComponentType<{
+        /** `loading` — список грузится, `error` — не загрузился (тогда `onRetry`), `ready` — `items` можно рисовать. */
+        status: "loading" | "ready" | "error";
+        items: ChatListItemView[];
+        onSelect: (chatId: string) => void;
+        /** «Новый чат». */
+        onCreate: () => void;
+        /** Новый чат создаётся: кнопку не нажимать повторно. */
+        creating: boolean;
+        /** Пустое и прежнее название слой поведения отбрасывает сам. */
+        onRename: (chatId: string, title: string) => void;
+        /** Просит подтверждения; сам ничего не удаляет. */
+        onRequestDelete: (chatId: string) => void;
+        /** Есть — показать окно подтверждения. */
+        deleteRequest?: ChatListDeleteRequestView;
+        /** Что пошло не так, готовой надписью (действие не удалось или список не загрузился). */
+        error?: string;
+        onRetry?: () => void;
+    }>;
+}

package/dist/types/chat-list/chat-workspace.d.ts

@@ -0,0 +1,17 @@
+import type { AgentChatProps } from "../agent-chat.js";
+import type { ChatSkin } from "../skin-contract.js";
+import type { ChatListSkin } from "./chat-list-skin.js";
+export interface ChatWorkspaceProps extends Omit<AgentChatProps, "chatId" | "subject" | "skin" | "onBusyChange" | "onChatUnavailable" | "initialDraft"> {
+    /** Скин чата плюс скин списка (например, `tandemSkin`). */
+    skin: ChatSkin & ChatListSkin;
+    /** Какой чат открыть первым, например из адреса страницы. Главнее запомненного; чата нет — «Чат не найден». */
+    initialChatId?: string;
+    /** Открытый чат сменился (выбор, создание, удаление): например, чтобы поменять адрес страницы. */
+    onChatChange?: (chatId: string | null) => void;
+}
+/**
+ * Чат со списком чатов рядом: выбрать, создать, переименовать, удалить. Всё видимое рисует скин. У открытого чата
+ * запрещено право `chatList` — списка нет, только чат: он не показывается и не обновляется, пока права открытого чата неизвестны
+ * (до первой истории) и если запрещён.
+ */
+export declare function ChatWorkspace({ skin, initialChatId, onChatChange, onChatAccessChange, ...chatProps }: ChatWorkspaceProps): import("react").JSX.Element;

package/dist/types/chat-list/use-chat-list-view.d.ts

@@ -0,0 +1,12 @@
+import type { ComponentProps } from "react";
+import type { ChatLabels } from "../labels.js";
+import type { ChatListSkin } from "./chat-list-skin.js";
+import type { ChatListState } from "./use-chat-list.js";
+export type ChatListViewProps = ComponentProps<ChatListSkin["ChatList"]>;
+/**
+ * Что получает `skin.ChatList`: строки, действия, подтверждение удаления и ошибка готовой надписью.
+ * `onChosen` — чат выбран или создан (например, чтобы закрыть список поверх чата). Общее у `ChatWorkspace` и панели агента.
+ */
+export declare function useChatListView(list: ChatListState, onChosen: () => void): ChatListViewProps;
+/** Название открытого чата для шапки; нет названия или чата нет в списке — «Новый чат». */
+export declare function activeChatTitle(list: Pick<ChatListState, "items" | "activeChatId">, labels: ChatLabels): string;

package/dist/types/chat-list/use-chat-list.d.ts

@@ -0,0 +1,47 @@
+import type { AppRefusal } from "../app-refusal.js";
+import type { ChatListEntry } from "./chat-list-client.js";
+export type ChatListStatus = "loading" | "ready" | "error";
+/** Какое действие не удалось; сам список не загрузился — `status: "error"`. */
+export type ChatListActionError = "create" | "rename" | "delete";
+export interface UseChatListOptions {
+    /** Адрес обработчика чата, например `/api/chat`. */
+    api: string;
+    /** Какой чат открыть первым (например, из адреса страницы). Главнее запомненного; чата нет в списке — откроется «Чат не найден». */
+    initialChatId?: string;
+    /** Свой `fetch` — для тестов и особых сред. */
+    fetch?: typeof globalThis.fetch;
+    /** Ключ запомненного чата. По умолчанию `agent-chat:active-chat:${api}`; у панели агента свой, на человека. Смена ключа — список загружается заново, прежний открытый чат не переносится. */
+    rememberKey?: string;
+    /** Приложение не дало создать чат (`chat_creation_refused`): та же весть, что `onTurnRefused` у чата. Текст отказа список показывает сам. */
+    onCreateRefused?: (refusal: AppRefusal) => void;
+}
+export interface ChatListState {
+    status: ChatListStatus;
+    items: ChatListEntry[];
+    /** Открытый чат; `null`, пока список грузится или не загрузился. */
+    activeChatId: string | null;
+    error: ChatListActionError | null;
+    /** Отказ приложения, из-за которого `error` — `create`: его слова показываются вместо общего «Не удалось создать чат». */
+    creationRefusal: AppRefusal | null;
+    creating: boolean;
+    /** Чат, удаление которого ждёт подтверждения. Удаляет только `confirmDelete`. */
+    deleteRequest: {
+        id: string;
+        title: string | null;
+    } | null;
+    deleting: boolean;
+    select(chatId: string): void;
+    /** Открывает пустой чат (без названия и без сообщений), если он уже есть, иначе создаёт новый. `false` — не вышло (`error` — `create`). */
+    create(): Promise<boolean>;
+    /** Пустое или прежнее название — ничего не делает. Не вышло — прежнее название возвращается. */
+    rename(chatId: string, title: string): Promise<void>;
+    requestDelete(chatId: string): void;
+    cancelDelete(): void;
+    confirmDelete(): Promise<void>;
+    /** Тихо обновляет список (название появилось, порядок сменился); отказ не показывается. */
+    refresh(): Promise<void>;
+    /** Загружает список заново после отказа. */
+    reload(): void;
+}
+/** Состояние списка чатов: загрузка, выбор открытого чата, создание, переименование и удаление. Ничего не рисует. */
+export declare function useChatList({ api, initialChatId, fetch: customFetch, rememberKey, onCreateRefused }: UseChatListOptions): ChatListState;

package/dist/types/chat-list/use-workspace-list-sync.d.ts

@@ -0,0 +1,7 @@
+import type { ChatListState } from "./use-chat-list.js";
+/**
+ * Список чатов следит за открытым чатом: ответ начался или закончился — тихое обновление (порядок и название могли
+ * измениться); пока идёт ответ, а названия у чата нет, — опрос раз в секунду. Общее у `ChatWorkspace` и панели агента.
+ * `enabled: false` — список не нужен (у чата запрещён `chatList`): ничего не запрашивается.
+ */
+export declare function useWorkspaceListSync(list: Pick<ChatListState, "items" | "activeChatId" | "refresh">, busy: boolean, enabled?: boolean): void;

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

@@ -0,0 +1,27 @@
+/** Состояние чата: значения, записанные инструментами (`model.state`), без служебных ключей SDK. */
+export type ChatStateValues = Record<string, unknown>;
+export declare const APP_STATE_PART_TYPE = "data-app-state";
+/** Свёртка записей состояния показанной ветки по порядку: в записи сначала `unset`, потом `set`. */
+export declare function foldChatState(messages: ReadonlyArray<{
+    parts: ReadonlyArray<{
+        type: string;
+    }>;
+}>): ChatStateValues;
+/** Состояние из события сервера (`state-changed`): объект без служебных ключей; не объект — `null`. */
+export declare function chatStateOfEvent(state: unknown): ChatStateValues | null;
+/** Одинаковые ли состояния: то же значение не перерисовывает экран и не зовёт `onStateChange` повторно. */
+export declare const sameChatState: (a: ChatStateValues, b: ChatStateValues) => boolean;
+export declare const ChatStateContext: import("react").Context<ChatStateValues>;
+/** Публикует состояние чата для `useChatState(chatId)`; возвращает смену значения и снятие с публикации. */
+export declare function publishChatState(chatId: string, values: ChatStateValues): {
+    update(values: ChatStateValues): void;
+    remove(): void;
+};
+/**
+ * Состояние чата показанной ветки, без служебных ключей. Без аргумента — внутри `AgentChat` (компоненты скина, виджеты,
+ * свои кнопки): живьём по ходу ответа и после смены ветки; вне `AgentChat` — пустое; с `useAgentChat` — поле
+ * `chatState`. С `chatId` — где угодно на странице (панель рядом с чатом): то же состояние, что у `AgentChat` или
+ * `useAgentChat` этого чата на странице, с теми же живыми обновлениями и без своих запросов. Чата на странице нет или
+ * его история ещё грузится — пустое.
+ */
+export declare function useChatState(chatId?: string): ChatStateValues;

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

@@ -0,0 +1,85 @@
+import type { UIMessage } from "ai";
+/** `awaiting_approval` — агент ждёт, разрешит ли человек вызов инструмента. */
+export type AnswerStatus = "streaming" | "complete" | "stopped" | "error" | "interrupted" | "awaiting_approval";
+export type ChatErrorKind = "overloaded" | "rate_limited" | "insufficient_funds" | "invalid_key" | "context_overflow" | "other";
+/**
+ * Что показывает `ErrorNotice`: ошибка ответа или отказ сервера чату целиком. `signed_out` — вход истёк (401),
+ * `too_many_turns` — у человека уже идут ответы в других чатах (429), ход не начат; `forbidden_origin` — сервер
+ * не признал страницу своей (403): фронт и API на разных адресах, а адреса фронта нет в `allowedOrigins` сервера.
+ */
+export type ErrorNoticeKind = ChatErrorKind | "signed_out" | "too_many_turns" | "forbidden_origin";
+/** Уровень рассуждений модели (как в профиле модели ядра). */
+export type ReasoningLevelId = "off" | "on" | "minimal" | "low" | "medium" | "high" | "max";
+/** Решение человека по запросу подтверждения. `always` — разрешить и больше не спрашивать про этот инструмент в этом чате. */
+export type ApprovalDecision = "allow" | "deny" | "always";
+/** Метка сервера в решении «Всегда в этом чате»; часть протокола, слово не менять. */
+export declare const ALWAYS_IN_CHAT = "always-in-chat";
+/** Метка сервера в запросе (`approval.requestReason`): для этого вызова «Всегда в этом чате» предложена; часть протокола, слово не менять. */
+export declare const ALWAYS_OFFERED = "always-offered";
+/**
+ * Почему ответ на запрос не принят: нет связи или сбой, лимит расходов, чат занят другим ходом, идут ответы в других чатах,
+ * приложение не пустило ход (`refused`: причина словами приложения лежит в `text` рядом с видом).
+ */
+export type ApprovalFailureKind = "connection" | "spending_limit" | "busy" | "too_many_turns" | "refused";
+/** Выбор собеседника, каким его хранит и отдаёт сервер. */
+export interface ChatModelChoice {
+    modelId: string;
+    providerId: string;
+    reasoning?: string;
+}
+export interface TokenUsage {
+    inputTokens: number;
+    cachedInputTokens: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    /** Размер контекста после ответа: вход плюс выход последнего шага. */
+    contextTokens?: number;
+    /** Есть, если числа «примерно»: прикинуты по длине текста, а не сообщены провайдером. */
+    estimated?: true;
+}
+/** Вид звука человека (смех, вздох…); копия закрытого списка ядра: ядро браузеру не нужно. */
+export type VoiceSound = "laughter" | "sigh" | "cough" | "sneeze" | "gasp" | "crying" | "yawn" | "groan";
+/** Отметка обрыва озвучки: человек перебил голосом. `partIndex`/`charOffset` — где оборвалось в тексте, `spokenTail` — хвост озвученного. */
+export interface VoiceCut {
+    partIndex: number;
+    charOffset: number;
+    spokenTail: string;
+}
+export interface ChatMessageMetadata {
+    modelId?: string;
+    providerId?: string;
+    usage?: TokenUsage;
+    /** Длительность рассуждений по порядковому номеру части рассуждения в сообщении. */
+    reasoningDurationsMs?: Record<string, number>;
+    status?: AnswerStatus;
+    error?: {
+        kind: ChatErrorKind;
+    };
+    /** Есть, если озвучку ответа оборвало перебивание. */
+    voiceCut?: VoiceCut;
+    /** Ответ не дошёл до человека (сервер пометил «не доставлено»): модель его не видит. */
+    undelivered?: true;
+}
+export type AgentChatMessage = UIMessage<ChatMessageMetadata>;
+/** Запись сжатия истории: сводка заменила для модели сообщения с `fromMessageId` по `throughMessageId`. */
+export interface CompactionMarker {
+    id: string;
+    fromMessageId: string;
+    throughMessageId: string;
+    /** Сводка в Markdown. */
+    summary: string;
+    summaryTokens: number;
+    createdAt: string;
+}
+/** Развилка на текущей ветке: сообщение и все его соседи по порядку создания, включая его самого. */
+export interface BranchFork {
+    messageId: string;
+    siblingIds: string[];
+}
+/**
+ * Текст сообщения из частей: абзацы через пустую строку. У ответа голосового хода (`voiceAnswer`) теги голоса вырезаны:
+ * человек видит, копирует и слышит диктором только слова. В остальных ответах скобки — обычный текст.
+ */
+export declare function messageText(message: AgentChatMessage, { voiceAnswer }?: {
+    voiceAnswer?: boolean;
+}): string;

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

@@ -0,0 +1,57 @@
+/**
+ * Подписка на события чата: `GET /:chatId/watch` отдаёт поток SSE, пока вкладка открыта.
+ * Обрыв или затянувшаяся тишина — переподключение с паузами; адреса нет — подписка заканчивается.
+ * Доступ закрыт (401, 403) — повтор через долгую паузу: вход могли восстановить. Вкладка, кроме того, открывает подписку
+ * заново после каждого своего хода.
+ */
+export type ChatWatchEvent = {
+    type: "turn-started";
+    messageId: string;
+    trigger: string;
+    channel: string;
+} | {
+    type: "turn-finished";
+    messageId?: string;
+} | {
+    type: "tasks-changed";
+} | {
+    type: "notice-added";
+    messageId: string;
+}
+/** Сообщение записано без хода (пачка из мессенджера ждёт тишины, «Стоп» отменил пачку). */
+ | {
+    type: "message-added";
+    messageId: string;
+} | {
+    type: "chat-closed";
+    closed: {
+        code: string;
+        message: string;
+    };
+} | {
+    type: "chat-reopened";
+}
+/** Состояние чата сменилось (ход, смена ветки, правка ответа — в том числе в другой вкладке). */
+ | {
+    type: "state-changed";
+    state: unknown;
+    atMessageId: string | null;
+} | {
+    type: string;
+    [key: string]: unknown;
+};
+export type WatchChatOptions = {
+    url: string;
+    fetch: (url: string, init?: RequestInit) => Promise<Response>;
+    signal: AbortSignal;
+    /** Паузы перед повторами по порядку; последняя повторяется. */
+    delaysMs: readonly number[];
+    /** Пауза перед повтором после 401 или 403. По умолчанию минута. */
+    refusedRetryMs?: number;
+    /** Сколько ждать хоть какого-то байта (событие или пинг), прежде чем считать поток мёртвым. */
+    silenceTimeoutMs: number;
+    onOpen?: () => void;
+    onEvent: (event: ChatWatchEvent) => void;
+};
+export type WatchChatEnd = "unavailable" | "stopped";
+export declare function watchChat(options: WatchChatOptions): Promise<WatchChatEnd>;

package/dist/types/close-stopped-tool-calls.d.ts

@@ -0,0 +1,8 @@
+import type { AgentChatMessage } from "./chat-types.js";
+type MessagePart = AgentChatMessage["parts"][number];
+/**
+ * Вызовы без окончательного результата закрыты: запущенные — ошибкой, ждавшие ответа человека или уже разрешённые — отказом
+ * (у разрешённого — «результат неизвестен», у отклонённого — причина человека). Остальное не тронуто.
+ */
+export declare function closeStoppedToolCalls(parts: readonly MessagePart[]): MessagePart[];
+export {};

package/dist/types/composer-actions.d.ts

@@ -0,0 +1,29 @@
+import type { ReactNode } from "react";
+/** Что `AgentChat.composerActions` может сделать с полем ввода и отправкой. */
+export interface ComposerHelper {
+    /** Текст в поле ввода сейчас. */
+    value: string;
+    /** Заменить текст в поле ввода. */
+    setValue(text: string): void;
+    /**
+     * Отправить сообщение по тем же правилам, что кнопка «Отправить». С `text` уходит он, поле не трогается;
+     * без `text` — то, что в поле (с файлами). Пока `canSend` ложно (история не загрузилась, идёт ответ, лимит исчерпан),
+     * обе формы отказывают сразу и ничего не откладывают: проверяйте `canSend` и гасите кнопку.
+     */
+    send(text?: string): void;
+    /** Положить файлы в поле ввода, как скрепка. Без плагина вложений ничего не делает. */
+    addFiles(files: File[]): void;
+    /** Агент отвечает: отправка сейчас не пройдёт. */
+    busy: boolean;
+    /** Отправка остановлена (исчерпан лимит расходов). */
+    blocked: boolean;
+    /** Отправка сейчас пройдёт: история загружена, ответ не идёт, лимит не исчерпан. */
+    canSend: boolean;
+}
+/**
+ * Свои кнопки у поля ввода: готовый узел или функция от помощника. Функция вызывается при каждом рендере чата:
+ * делайте её быстрой и без побочных эффектов; помощника не сохраняйте, каждый раз приходит новый.
+ */
+export type ComposerActions = ReactNode | ((composer: ComposerHelper) => ReactNode);
+/** Готовый узел для `Composer.actions` скина; `undefined` — кнопок нет. */
+export declare function renderComposerActions(actions: ComposerActions, helper: ComposerHelper): ReactNode;

package/dist/types/diagrams/diagram-renders.d.ts

@@ -0,0 +1,16 @@
+import type { DiagramsClient } from "../agent-chat-extensions.js";
+import type { DiagramColors } from "../skin-contract.js";
+export type DiagramRenderResult = {
+    svg: string;
+} | {
+    error: string;
+};
+/**
+ * Готовые рисунки чата по `source + colors`. Рисунок, уже готовый, отдаётся сразу: сообщение, которое лента убрала
+ * и вернула, показывает схему без заглушки, и лента не прыгает.
+ */
+export interface DiagramRenders {
+    get(source: string, colors: DiagramColors): DiagramRenderResult | undefined;
+    request(source: string, colors: DiagramColors): Promise<DiagramRenderResult>;
+}
+export declare function createDiagramRenders(client: DiagramsClient): DiagramRenders;

package/dist/types/diagrams/mermaid-blocks.d.ts

@@ -0,0 +1,18 @@
+/** Кусок текста ответа: обычная разметка или блок ```mermaid. */
+export type MarkdownSegment = {
+    kind: "markdown";
+    markdown: string;
+}
+/** `source` — текст схемы без ограждений; `closed` — блок закрыт; `markdown` — блок целиком, как в тексте. */
+ | {
+    kind: "mermaid";
+    source: string;
+    closed: boolean;
+    markdown: string;
+};
+/**
+ * Делит Markdown на обычные куски и блоки ```mermaid верхнего уровня (по правилам ограждений CommonMark): блок внутри
+ * другого блока кода и блок с отступом в четыре пробела — не схема. Номер схемы — её порядок среди кусков `mermaid`;
+ * им скин зовёт `renderDiagram(source, blockIndex)`, и слой поведения считает так же.
+ */
+export declare function splitMermaidBlocks(markdown: string): MarkdownSegment[];

package/dist/types/diagrams/unique-svg-ids.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Разметка схемы со своими id для одной вставки в страницу. Один готовый рисунок из кэша может стоять в ленте
+ * дважды и ещё в окне просмотра; при одинаковых id `url(#…)` берёт первый в странице, и стрелки пропадают вместе
+ * с ним. Каждый id рисунка получает суффикс вставки, ссылки на него в атрибутах и стилях — тоже.
+ */
+export declare function withUniqueIds(svg: string, suffix: string): string;

package/dist/types/diagrams/use-diagram-blocks.d.ts

@@ -0,0 +1,25 @@
+import type { MediaViewerItem } from "../media-viewer/media-viewer-types.js";
+import type { DiagramColors, DiagramView } from "../skin-contract.js";
+import type { DiagramRenders } from "./diagram-renders.js";
+/** Сколько блоков ```mermaid в тексте: по нему номера схем следующей текстовой части продолжают нумерацию ответа. */
+export declare const countMermaidBlocks: (markdown: string) => number;
+export interface UseDiagramBlocksOptions {
+    markdown: string;
+    /** Текстовая часть ещё печатается. */
+    streaming: boolean;
+    messageId: string;
+    /** Номер первой схемы этой части в ответе: схемы прежних текстовых частей того же ответа. */
+    firstBlock: number;
+    renders: DiagramRenders;
+    colors: DiagramColors;
+    /** Открыть окно просмотра своим набором; нет — схема не открывается. */
+    open?: (key: string, trigger: HTMLElement, items: readonly MediaViewerItem[]) => void;
+}
+/**
+ * Схемы одной текстовой части для скина (`AgentText.renderDiagram`/`onOpenDiagram`). Незакрытый блок, пока текст
+ * печатается, — `streaming`; закрытый рисуется сразу, не дожидаясь конца ответа; дальше `ready` или `failed`.
+ */
+export declare function useDiagramBlocks({ markdown, streaming, messageId, firstBlock, renders, colors, open }: UseDiagramBlocksOptions): {
+    renderDiagram: (source: string, blockIndex: number) => DiagramView;
+    onOpenDiagram?: ((blockIndex: number, trigger: HTMLElement) => void) | undefined;
+};

package/dist/types/diagrams/use-diagram-colors.d.ts

@@ -0,0 +1,8 @@
+import type { ChatSkin, DiagramColors } from "../skin-contract.js";
+/** Тёмная ли страница, со слежением за сменой темы; `enabled: false` — не следит и отдаёт `false`. */
+export declare function usePageDark(enabled: boolean): boolean;
+/**
+ * Цвета схем для текущей темы страницы (FR-028): `skin.diagramColors(dark)`, без него — свои. Смена темы даёт новые
+ * цвета, и схемы перерисовываются. `enabled: false` (схемы не подключены) — за темой не следит и отдаёт `undefined`.
+ */
+export declare function useDiagramColors(skin: ChatSkin, enabled: boolean): DiagramColors | undefined;

package/dist/types/dictation-field.d.ts

@@ -0,0 +1,19 @@
+import type { DictatedText } from "./voice-input.js";
+/**
+ * Как диктовка пишет в поле ввода. Продиктованное дописывается к тому, что было набрано;
+ * ручная правка остаётся, а сказанное до неё заново не появляется.
+ */
+export interface DictationField {
+    /** Значение поля для накопленной диктовки; `null` — поле не трогать (диктовка уже заморожена). */
+    write(text: DictatedText): string | null;
+    /** Сообщить, что в поле сейчас `value`: если это не наша запись, значит поле правили руками. */
+    observe(value: string): void;
+    /** Сказано всё и закреплено, дальше только чистка: правки поля запоминаем, но запись больше не двигаем и `write` ничего не пишет. */
+    freeze(): void;
+    /**
+     * Заменить надиктованный кусок исправленным текстом. Возвращает новое значение поля или `null`, если заменять нельзя:
+     * поле правили до надиктованного или внутри него (правка не должна пропасть). Дописанное после надиктованного сохраняется.
+     */
+    applyPolished(polished: string): string | null;
+}
+export declare function createDictationField(startValue: string): DictationField;

package/dist/types/expanded-parts.d.ts

@@ -0,0 +1,11 @@
+export interface ExpandedParts {
+    isOpen: (key: string) => boolean;
+    setOpen: (key: string, open: boolean) => void;
+    subscribe: (listener: () => void) => () => void;
+}
+/** Ключ части ответа: id сообщения и номер части. */
+export declare function partKey(messageId: string, partIndex: number): string;
+/** Хранилище раскрытых частей одного чата; при смене `chatId` начинается пустое. */
+export declare function useExpandedParts(chatId: string): ExpandedParts;
+/** Раскрыта ли часть и как её переключить; часть перерисовывается только от своего ключа. */
+export declare function usePartOpen(store: ExpandedParts, key: string): [boolean, (open: boolean) => void];

package/dist/types/feed-announcement.d.ts

@@ -0,0 +1,7 @@
+import type { AgentChatMessage } from "./chat-types.js";
+/**
+ * Текст для диктора: пустой при открытии чата, итог ответа — когда ответ перешёл из «идёт» в
+ * итоговое состояние. Когда начинается новый ответ, текст обнуляется: так одинаковые итоги
+ * подряд («Остановлено» дважды) озвучиваются оба раза. `resetKey` (id чата) тоже обнуляет текст.
+ */
+export declare function useFeedAnnouncement(messages: AgentChatMessage[], busy: boolean, resetKey?: string): string;