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

package/dist/types/spending-status.d.ts

@@ -0,0 +1,76 @@
+/** Чей лимит и за какой срок; как в ответе сервера. */
+export type SpendingScope = "user" | "chat" | "service";
+/** `rolling` — окно на `hours` часов от первого запроса. */
+export type SpendingPeriod = "month" | "week" | "day" | "rolling" | "none";
+/** Почему ход не начнётся: лимит исчерпан, человек заблокирован или остаток меньше запаса на новый ответ. */
+export type SpendingRefusalReason = "limit" | "blocked" | "reserve";
+/** Одно окно лимита: доля и срок, без долларов. У окна сообщений — и сами числа. */
+export interface SpendingWindowInfo {
+    id: string;
+    scope: SpendingScope;
+    period: SpendingPeriod;
+    hours?: number;
+    state: "ok" | "warning" | "exhausted";
+    share: number;
+    resetsAt: Date | null;
+    /** Окно считает сообщения человека; нет — деньги. */
+    unit?: "messages";
+    /** Окно сообщений: лимит, отправлено и осталось. */
+    limit?: number;
+    used?: number;
+    remaining?: number;
+}
+/** Что известно о лимите: из этого слой поведения собирает надпись. Долларов здесь нет. */
+export interface SpendingInfo {
+    scope: SpendingScope;
+    period: SpendingPeriod;
+    /** Длина скользящего окна в часах. */
+    hours?: number;
+    /** Доля израсходованного, 0…1 и больше при перерасходе; `null` — сервер её не назвал (отказ хода). */
+    share: number | null;
+    /** Когда расход обнулится; `null` — никогда. */
+    resetsAt: Date | null;
+    /** Пояс лимитов (IANA), по которому показывать дату обновления; нет — UTC. */
+    timeZone?: string;
+    /** Почему ход не начнётся (лимиты с окнами); нет — исчерпан лимит. */
+    reason?: SpendingRefusalReason;
+    /** Имя самого тесного окна (лимиты с окнами). */
+    windowId?: string;
+    /** Все окна с лимитом по отдельности (лимиты с окнами): приложение может показать их сами. */
+    windows?: SpendingWindowInfo[];
+    /** Самое тесное окно считает сообщения человека; нет — деньги. */
+    unit?: "messages";
+    /** Сколько сообщений осталось в этом окне; в отказе 429 числа нет. */
+    remaining?: number;
+}
+/** Лимит, о котором надо сказать собеседнику: пока всё в пределах, показывать нечего. */
+export interface SpendingView {
+    state: "warning" | "exhausted";
+    info: SpendingInfo;
+}
+/** Ответ сервера на `GET …/spending` и тело отказа 429 (в отказе `state` нет). */
+interface WireSpending {
+    state?: string;
+    scope?: string;
+    period?: string;
+    hours?: number;
+    share?: number;
+    resetsAt?: string | null;
+    timeZone?: string;
+    reason?: string;
+    windowId?: string;
+    blocked?: boolean;
+    windows?: unknown;
+    unit?: string;
+    remaining?: number;
+}
+/** Не дальше, чем умеет `setTimeout`: месяц с лишним в него не влезает. */
+export declare const MAX_TIMER_MS = 2147483647;
+/** Как часто спрашивать сервер, если срок обновления уже прошёл, а лимит ещё стоит (часы вкладки и сервера расходятся). */
+export declare const RESET_RECHECK_MS = 5000;
+export declare function spendingInfoOf(wire: WireSpending): SpendingInfo;
+/** `null` — лимит в пределах или ответ не разобрать: надписи нет. */
+export declare function spendingViewOf(wire: WireSpending): SpendingView | null;
+/** Через сколько спросить сервер снова, чтобы снять исчерпание сразу после обновления. */
+export declare function untilResetCheckMs(info: SpendingInfo, now: number): number | null;
+export {};

package/dist/types/steering/corrections.d.ts

@@ -0,0 +1,19 @@
+import type { FileUIPart } from "ai";
+import type { AgentChatMessage } from "../chat-types.js";
+/** Отметка поправки в частях сообщения: написано во время ответа (как у сервера, core: steering/turn-steering.ts). */
+export declare const STEER_PART_TYPE = "data-agent-steer";
+/** Поправка на экране: текст и файлы человека с отметкой поправки. */
+export declare function correctionMessage(id: string, text: string, files: readonly FileUIPart[]): AgentChatMessage;
+export declare function isCorrection(message: Pick<AgentChatMessage, "role" | "parts">): boolean;
+/**
+ * Ответы, за которыми идёт поправка: агент закончил их на границе шага, чтобы взять поправку. Пустой такой ответ —
+ * не «модель не дала ответа». Строка номеров через пробел: не меняется, пока не меняется состав.
+ */
+export declare function steeredAnswerIdsOf(feed: readonly AgentChatMessage[]): string;
+/** Сообщение для `POST …/steer`: отметку поправки сервер ставит сам. */
+export declare function outgoingCorrection(correction: AgentChatMessage): AgentChatMessage;
+/**
+ * Поправки после чтения истории: ждущие на сервере, затем свои, что ещё идут на сервер. Своя, которая уже в ленте
+ * или среди ждущих, второй раз не показывается.
+ */
+export declare function correctionsAfterHistory(waiting: readonly AgentChatMessage[], shown: readonly AgentChatMessage[], own: readonly AgentChatMessage[], sendingIds: ReadonlySet<string>): AgentChatMessage[];

package/dist/types/step-reset.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Отметка ядра «шаг начат заново у другого провайдера»: всё от последней части `step-start` до неё стёрто.
+ * Копия логики ядра (`withoutResetSteps`): React не зависит от ядра. Что копии совпадают, проверяет общий тест.
+ */
+export declare const STEP_RESET_PART_TYPE = "data-step-reset";
+/** Части ответа без стёртых шагов: каждая часть `data-step-reset` убирает себя и всё от последней `step-start` перед ней. Сброса нет — тот же массив. */
+export declare function withoutResetSteps<Part extends {
+    type: string;
+}>(parts: readonly Part[]): Part[];
+/** Сообщения без стёртых шагов; ничего не стёрто — тот же массив. */
+export declare function withoutResetMessages<Message extends {
+    parts: Array<{
+        type: string;
+    }>;
+}>(messages: Message[]): Message[];

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

@@ -0,0 +1,8 @@
+import type { ChatSkin } from "../skin-contract.js";
+/**
+ * Чат объекта ещё ищется: тот же вид, что у обычного чата, пока грузится история, — пустая лента и поле ввода без
+ * отправки. Экран не прыгает, когда чат найден.
+ */
+export declare function SubjectChatLoading({ skin }: {
+    skin: ChatSkin;
+}): import("react").JSX.Element;

package/dist/types/subject-chat/use-subject-chat-id.d.ts

@@ -0,0 +1,21 @@
+import type { AppRefusal } from "../app-refusal.js";
+/** Чат объекта: ещё ищется, найден (id), сервер отказал с текстом или запрос не удался (можно повторить). */
+export type SubjectChatState = {
+    state: "loading";
+} | {
+    state: "ready";
+    chatId: string;
+} | {
+    state: "refused";
+    text: string;
+} | {
+    state: "failed";
+};
+/**
+ * `POST {api}/subject { key }` при открытии и смене ключа: сервер находит или создаёт чат объекта человека. Ответ
+ * помнится вместе с запросом, на который он пришёл: при смене ключа прежний чат не показывается ни одного кадра.
+ * Отказ самого приложения (`turn_refused`, `access_refused`) уходит в `onAppRefusal` — по разу на ответ сервера.
+ */
+export declare function useSubjectChatId(api: string, subject: string, onAppRefusal?: (refusal: AppRefusal) => void): SubjectChatState & {
+    retry: () => void;
+};

package/dist/types/thinking-status/thinking-status.d.ts

@@ -0,0 +1,33 @@
+import type { ReactNode } from "react";
+/** Как часто сменяется фраза ожидания. Таймер тикает раз в секунду, поэтому фраза держится 3–4 с. */
+export declare const THINKING_PHRASE_MS = 3500;
+/** Номер следующей фразы: любой, кроме предыдущего. */
+export declare function nextThinkingPhraseIndex(count: number, previous: number, random?: () => number): number;
+/** Часы всех ответов чата по id: лента выгружает ответ, ушедший из вида, а его счёт сохраняется. */
+export declare function ThinkingClocksProvider({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * Общие часы ожидания одного ответа: строка «думает» без текста и блок рассуждений после неё продолжают тот же счёт
+ * и ту же череду фраз. `AgentChat` ставит его вокруг каждого ответа агента. С `id` внутри `ThinkingClocksProvider` часы
+ * переживают перемонтирование; ответ дописан (`waiting: false`) — часы забываются.
+ */
+export declare function ThinkingClockProvider({ id, waiting, children }: {
+    id?: string;
+    waiting?: boolean;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export interface ThinkingStatus {
+    /** Текущая фраза: из `labels.thinkingPhrases`, пустой набор — `labels.reasoningRunning`. */
+    phrase: string;
+    /** Секунды с начала ожидания ответа. */
+    seconds: number;
+    /** Те же секунды словами: «12 с», «1 мин 5 с» (`labels.thinkingElapsed`). */
+    elapsed: string;
+}
+/**
+ * Живая надпись, пока модель думает: фраза сменяется каждые 3–4 с без повтора подряд, рядом — время ожидания.
+ * Неактивная (`active: false`) таймер не держит. Скин рисует фразу и время сам; для экранного диктора — постоянная
+ * `labels.reasoningRunning`, а меняющиеся фразы от него скрыты, чтобы не зачитывались каждые три секунды.
+ */
+export declare function useThinkingStatus(active?: boolean): ThinkingStatus;

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

@@ -0,0 +1,14 @@
+import type { AgentChatMessage, AnswerStatus } from "./chat-types.js";
+/** Ход закончен на экране: ответ получил итог. */
+export interface TurnFinishedEvent {
+    chatId: string;
+    /** Id ответа агента — тот же, что в истории на сервере. */
+    messageId: string;
+    status: Exclude<AnswerStatus, "streaming">;
+}
+/**
+ * Зовёт `onTurnFinished` один раз на ход: чат был занят ответом, освободился, и у последнего ответа есть итог
+ * (законченный, остановленный, с ошибкой, прерванный, ждущий человека). Открытие чата с готовой историей хода не даёт.
+ * Ответ, законченный ради поправки, — свой ход и на сервере: он получает событие первым, перед ответом на поправку.
+ */
+export declare function useTurnFinishedReport(chatId: string, busy: boolean, messages: readonly AgentChatMessage[], onTurnFinished: ((turn: TurnFinishedEvent) => void) | undefined): void;

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

@@ -0,0 +1,228 @@
+import type { FileUIPart } from "ai";
+import type { AgentChatMessage, ApprovalDecision, ApprovalFailureKind, BranchFork, ChatModelChoice, CompactionMarker, VoiceCut, VoiceSound } from "./chat-types.js";
+import type { SpendingView } from "./spending-status.js";
+import type { AgentAppBridge } from "./app-bridge/app-bridge.js";
+import type { AppRefusal } from "./app-refusal.js";
+import type { ServerRefusal } from "./server-refusal.js";
+import type { ChatCapabilities, ChatClosure } from "./chat-access.js";
+import type { AppEvent } from "./app-events.js";
+import type { WidgetFailureKind } from "./widgets/use-widget-answer.js";
+import type { ChatStateValues } from "./chat-state/chat-state.js";
+/** Настройки живой связи. Всё необязательно: по умолчанию сроки из договора 002. */
+export interface LivenessOptions {
+    /** Сколько тишины терпеть в потоке ответа. По умолчанию 30 000 мс. */
+    silenceTimeoutMs?: number;
+    /** Паузы перед попытками переподключения. По умолчанию [0, 2000, 5000]. */
+    reconnectDelaysMs?: readonly number[];
+    /** Срок одной попытки и любого запроса без потока. По умолчанию 10 000 мс. */
+    requestTimeoutMs?: number;
+}
+/** Как вкладка видит связь с сервером. */
+export type ConnectionState = "online" | "reconnecting" | "offline";
+export interface UseAgentChatOptions {
+    /** Адрес обработчика чата, например `/api/chat`. */
+    api: string;
+    chatId: string;
+    /** Свой `fetch` — для тестов и особых сред. */
+    fetch?: typeof globalThis.fetch;
+    liveness?: LivenessOptions;
+    /** У сервера включены лимиты расходов: читать состояние лимита и показывать его. Отказ 429 обрабатывается всегда. */
+    spendingLimits?: boolean;
+    /** Связь с приложением: место, вкладка, сообщения об изменении данных, браузерные вызовы. Нет — чат как раньше. */
+    appBridge?: AgentAppBridge;
+    /** Текст в поле ввода при открытии чата. */
+    initialDraft?: string;
+    /** Приложение отказало ходу или человеку в доступе: код для программы и слова для человека. Зовётся на каждый такой отказ. */
+    onTurnRefused?: (refusal: AppRefusal) => void;
+    /**
+     * Событие приложения пришло по каналу наблюдения: вне хода (`publishAppEvent` на сервере, без `messageId`) или от
+     * хука итога, доделанного после «Стопа» (`messageId` — ответ, куда оно уже дописано; история перечитывается сама).
+     * Канал открыт, пока чат свободен: событие, опубликованное во время хода, вкладка не получит. События в ответах
+     * читает `AgentChat.onAppEvent`.
+     */
+    onAppEvent?: (event: AppEvent, messageId?: string) => void;
+    /**
+     * Новые события ответа `messageId` придут живыми с перечитанной историей: ответ на виджет принят без продолжения,
+     * события его проверки уже дописаны в ответ. `AgentChat` передаёт сюда `expectLive` учёта ленты.
+     */
+    onExpectLiveAppEvents?: (messageId: string) => void;
+    /**
+     * Поправки на лету: пока идёт ответ, `submit` отправляет текст поправкой (`POST …/steer`), агент берёт её на ближайшем
+     * шаге. Своя лента включает их явно (`true`) и рисует `corrections` после `messages`; по умолчанию выключено — во время
+     * ответа поле не отправляет, как до 0.34.
+     */
+    steering?: boolean;
+    /** Другое значение — история перечитывается с сервера (права, закрытие, лента): чат изменился не через экран. Первое значение ничего не перечитывает. */
+    reloadKey?: number;
+}
+export interface AgentChatState {
+    messages: AgentChatMessage[];
+    /** Записи сжатия истории на текущей ветке: на их границах лента рисует разделители. */
+    compactions: CompactionMarker[];
+    /** Развилки текущей ветки: у сообщения с соседями лента рисует переключатель «‹ 2/3 ›». */
+    forks: BranchFork[];
+    /** История загружена с сервера. */
+    loaded: boolean;
+    value: string;
+    setValue: (value: string) => void;
+    canSubmit: boolean;
+    /**
+     * Идёт ответ, и поле принимает поправки: `submit` отправит текст (или файлы) поправкой, агент возьмёт её на ближайшем
+     * шаге. Пустое поле `submit` не отправит, как и при `canSubmit`.
+     */
+    canSteer: boolean;
+    /**
+     * Поправки, которые агент ещё не взял: лента рисует их после сообщений, с пометкой. Взятая поправка уходит отсюда в
+     * `messages`.
+     */
+    corrections: AgentChatMessage[];
+    /** Идёт ответ или вкладка переподключается к нему. */
+    busy: boolean;
+    /** Отправляет введённый текст; `files` — готовые вложения (ссылки на загруженные файлы): тогда текст может быть пуст. */
+    submit: (files?: readonly FileUIPart[], onRejected?: (kind: string | undefined) => void) => boolean;
+    stop: () => Promise<void>;
+    /**
+     * Отправляет слова из голосового режима (с признаком `voiceMode`, чтобы ответ был коротким и разговорным).
+     * `false` — не ушло: пусто, чат не загружен, ответ ещё идёт, лимит исчерпан или ждёт подтверждения инструмента.
+     */
+    sendVoiceMessage: (text: string, options?: {
+        sounds?: readonly VoiceSound[];
+    }) => boolean;
+    /** Ставит у ответа отметку обрыва озвучки на экране; на сервер ничего не уходит. */
+    showVoiceCut: (messageId: string, cut: VoiceCut) => void;
+    /**
+     * Склейка голосовых фраз: останавливает ход, у которого ещё нет ничего, кроме размышления, и правкой заменяет последнее
+     * голосовое сообщение новым текстом (прежнее с пустым ответом уходит в соседнюю ветку); модель отвечает на новое.
+     * `sounds` — звуки человека, пойманные с этой частью фразы: уходят на сервер, на экране не видны.
+     * Выполнено, когда сервер принял правку. `false` — заменить нельзя (у ответа уже есть текст или вызов инструмента,
+     * сообщение не голосовое, сервер отказал): сообщение не заменено, ход мог быть остановлен.
+     * Вызовы идут по очереди.
+     */
+    replaceLastVoiceMessage: (text: string, options?: {
+        sounds?: readonly VoiceSound[];
+    }) => Promise<boolean>;
+    /** Последний ответ можно повторить: ошибка, стоп, прерывание или пустой ответ. */
+    canRetry: boolean;
+    /** Сообщение собеседника не дошло до сервера. */
+    sendFailed: boolean;
+    /** История чата не загрузилась: сервер ответил ошибкой. */
+    loadFailed: boolean;
+    /** Сервер ответил 404: чат чужой или его нет. Это окончательно, повторять нечего. */
+    notFound: boolean;
+    /** Выбор модели, сохранённый в чате (из истории); `null`, пока история не загружена и при скрытой модели. */
+    savedModelChoice: ChatModelChoice | null;
+    /** Видит ли модель чата картинки — из истории; `undefined`, пока история не пришла, модели нет в каталоге или сервер старый. */
+    modelAcceptsImages: boolean | undefined;
+    /**
+     * В чат попал чужой текст — из истории или куском потока посреди ответа. Раз появившись, не пропадает: чужой текст
+     * остаётся в истории чата. Живые демонстрации в таком чате не запускаются.
+     */
+    externalContent: boolean;
+    /** Связь с сервером: обычная работа, идут попытки подключиться, попытки исчерпаны. */
+    connection: ConnectionState;
+    /**
+     * Новый ответ на последний вопрос; если вопрос не дошёл до сервера — отправляет его заново;
+     * если не загрузилась история — грузит её снова; при «Нет связи» — начинает попытки заново.
+     */
+    retry: () => void;
+    /** Ответ человека на запрос подтверждения; когда отвечены все запросы, ход продолжается и лента дописывается. */
+    respondToApproval: (approvalId: string, decision: ApprovalDecision) => Promise<void>;
+    /** Запрос, ответ на который сейчас идёт на сервер. */
+    approvalPendingId: string | null;
+    /** Запрос, ответ на который не принят (нет связи, лимит, чат занят): кнопки снова доступны. */
+    approvalFailure: {
+        id: string;
+        kind: ApprovalFailureKind;
+        text?: string;
+    } | null;
+    /**
+     * Ответ человека на виджет (вызов `toolCallId`); `true` — сервер принял, ход продолжается и лента дописывается.
+     * `onAccepted` — сразу, как сервер принял, не дожидаясь продолжения.
+     */
+    answerWidget: (toolCallId: string, answer: unknown, onAccepted?: () => void) => Promise<boolean>;
+    /** Виджет, ответ на который сейчас идёт на сервер. */
+    widgetPendingId: string | null;
+    /** Виджет, ответ на который не принят: он снова активен. */
+    widgetFailure: {
+        id: string;
+        kind: WidgetFailureKind;
+        text?: string;
+    } | null;
+    /** Обычная отправка готового текста мимо поля ввода (подсказка ответа); `false` — не ушло. */
+    sendReply: (text: string) => boolean;
+    /** Переключает текущую ветку на соседнее сообщение развилки; во время ответа не делает ничего. `true` — история новой ветки показана. */
+    selectBranch: (messageId: string) => Promise<boolean>;
+    /** Последний ответ можно переделать: он законченный и непустой (у остальных — «повторить»). */
+    canRegenerate: boolean;
+    /** Новый ответ на последний вопрос; прежний остаётся соседней веткой. */
+    regenerate: () => void;
+    /** Отправленное сообщение можно править: ничего не идёт и связь есть. */
+    canEdit: boolean;
+    /**
+     * Правка отправленного сообщения: новая ветка от того же места с новым текстом и новым ответом.
+     * Отвечает, как только сервер принял правку или отказал, не дожидаясь конца ответа. При отказе лента возвращается
+     * к прежнему виду: тексту, который собеседник правил, есть куда вернуться.
+     */
+    edit: (messageId: string, text: string) => Promise<EditOutcome>;
+    /** Лимит расходов подошёл к пределу или исчерпан; `null` — всё в пределах, лимитов нет или они не включены. */
+    spending: SpendingView | null;
+    /**
+     * Сервер отказал не из-за связи: `signed_out` — вход истёк (401), `too_many_turns` — у человека уже идут ответы
+     * в других чатах, `forbidden_origin` — сервер не признал страницу своей (403, адреса нет в `allowedOrigins`).
+     * `null` — отказа нет. Вход снимается любым успешным запросом, остальные — принятым ходом и сменой чата.
+     */
+    refusal: ChatRefusal | null;
+    /**
+     * Приложение не пустило человека в этот чат (`resolveUser` вернул отказ) на загрузке истории: слова приложения вместо чата.
+     * `null` — доступ есть.
+     */
+    accessRefusal: ServerRefusal | null;
+    /**
+     * Сервер отказал ходу 4xx с понятным текстом (`{ error: "…" }` или `{ error: { message: "…" } }`): текст до
+     * 300 знаков. `final` — повтор того же запроса снова получит отказ (всё, кроме 408, 425 и 429): «Повторить» не нужна.
+     * Отправленное сообщение при окончательном отказе возвращается в поле. Снимается следующим ходом и сменой чата.
+     * Отказ правке показывает сам редактор. `null` — такого отказа нет.
+     */
+    serverRefusal: ServerRefusal | null;
+    /**
+     * Счётчик «список фоновых задач мог измениться»: растёт при каждом открытии подписки `GET {chat}/watch` и на её
+     * событие `tasks-changed`. Сервер без подписки — всегда 0.
+     */
+    tasksVersion: number;
+    /** Сервер не заявил, что фона у него нет (`backgroundTasks: false` в истории): задачи можно спрашивать. Старый сервер без заявки — `true`. */
+    backgroundTasksAvailable: boolean;
+    /** Права человека в чате (из истории); сервер до 0.27 их не присылает — всё разрешено. */
+    capabilities: ChatCapabilities;
+    /**
+     * Чат закрыт: отправка, «Повторить», виджеты и подтверждения недоступны. Правка, «Переделать», ветки и правка ответа
+     * уводят с точки закрытия и идут по правам (`capabilities`). Приходит с историей, отказом 409 `chat_closed`, куском
+     * потока ответа и событиями наблюдения. `null` — чат открыт.
+     */
+    closed: ChatClosure | null;
+    /** Состояние чата показанной ветки (`model.state` на сервере): живьём по ходу ответа и после смены ветки. */
+    chatState: ChatStateValues;
+}
+/** Отказ сервера, о котором говорит надпись над полем ввода. */
+export type ChatRefusal = "signed_out" | "too_many_turns" | "forbidden_origin";
+/** Причина, по которой правка не ушла на сервер. */
+export type EditNotStartedReason = "busy" | "offline" | "empty" | "unknown_message";
+/** Причина отказа сервера: ответ уже идёт, правка неверна, сообщения в чате нет, лимит расходов исчерпан. */
+export type EditRefusalReason = "busy" | "invalid" | "not_found" | "spending_limit" | "signed_out" | "too_many_turns" | "forbidden_origin" | "server_refused";
+/**
+ * Чем кончилась попытка правки. `started` — сервер принял, идёт новый ответ (обрыв связи после этого — обычный путь «Повторить»).
+ * У `server_refused` есть `text` — причина отказа словами сервера (4xx с текстом); если отказало приложение — ещё и `code`.
+ * У `spending_limit` из-за окна сообщений — `unit: "messages"`; у денег поля нет.
+ */
+export type EditOutcome = {
+    status: "started";
+} | {
+    status: "not_started";
+    reason: EditNotStartedReason;
+} | {
+    status: "refused";
+    reason: EditRefusalReason;
+    text?: string;
+    code?: string;
+    unit?: "messages";
+};
+export declare function useAgentChat({ api, chatId, fetch: customFetch, liveness, spendingLimits, appBridge, initialDraft, onTurnRefused, onAppEvent, onExpectLiveAppEvents, reloadKey, steering, }: UseAgentChatOptions): AgentChatState;

package/dist/types/use-model-choice.d.ts

@@ -0,0 +1,31 @@
+import type { ChatModelChoice } from "./chat-types.js";
+import type { ModelChoiceView } from "./skin-contract.js";
+export interface UseModelChoiceOptions {
+    /** Адрес обработчика чата, например `/api/chat`. */
+    api: string;
+    chatId: string;
+    /** Выбор, сохранённый в чате (из истории). Пока его нет, показывается выбор по умолчанию. */
+    savedChoice?: ChatModelChoice | null;
+    /**
+     * История чата ещё грузится, и выбор чата не пришёл. Пока это так, выбор по умолчанию не показывается: у нового чата
+     * выбор человека уже запомнен на сервере, и показ выбора по умолчанию мигнул бы чужой моделью.
+     */
+    savedChoicePending?: boolean;
+    /**
+     * Нужно ли меню. `false` — меню не запрашивается: права ещё не пришли с историей или модель скрыта
+     * (`modelDetails: false`). По умолчанию `true`.
+     */
+    menuWanted?: boolean;
+    /** Свой `fetch` — для тестов и особых сред. */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Человек выбрал модель или уровень в меню, и сервер сохранил выбор: получает его, как он сохранён. Выбор по
+     * умолчанию, выбор из истории и отказ сервера его не зовут.
+     */
+    onModelChosen?: (choice: ChatModelChoice) => void;
+}
+/**
+ * Выбор модели и уровня рассуждений для поля ввода. Живёт отдельно от `useAgentChat`, чтобы смена выбора
+ * не перерисовывала ленту. Смена видна сразу; при отказе сервера выбор откатывается к последнему сохранённому.
+ */
+export declare function useModelChoice({ api, chatId, savedChoice, savedChoicePending, menuWanted, fetch: customFetch, onModelChosen }: UseModelChoiceOptions): ModelChoiceView;

package/dist/types/use-voice-dialog.d.ts

@@ -0,0 +1,18 @@
+import type { VideosClient } from "./agent-chat-extensions.js";
+import type { AgentChatState } from "./use-agent-chat.js";
+import type { VoiceDialogEngine, VoiceDialogView } from "./voice-dialog.js";
+type DialogChat = Pick<AgentChatState, "messages" | "busy" | "stop" | "sendVoiceMessage" | "replaceLastVoiceMessage" | "showVoiceCut">;
+export interface UseVoiceDialogOptions {
+    /** Голосовой режим приложения; нет — кнопки нет и `useVoiceDialog` возвращает `undefined`. */
+    engine: VoiceDialogEngine | undefined;
+    chatId: string;
+    chat: DialogChat;
+    /** Видео агента: на месте показанного видео звучит `labels.voice.videoOnScreen`. */
+    videos?: VideosClient;
+}
+/**
+ * Связывает голосовой режим с чатом: даёт движку мост (отправка слов, остановка, текст ответа, конец ответа, отметка
+ * обрыва) и возвращает вид для кнопки в поле ввода. Мост не знает, как режим слушает и говорит; движок не знает, как устроен чат.
+ */
+export declare function useVoiceDialog({ engine, chatId, chat, videos }: UseVoiceDialogOptions): VoiceDialogView | undefined;
+export {};

package/dist/types/use-voice-dictation.d.ts

@@ -0,0 +1,17 @@
+import type { VoiceInputView } from "./skin-contract.js";
+import type { VoiceInput } from "./voice-input.js";
+export interface UseVoiceDictationOptions {
+    /** Нет голоса — нет и кнопки. */
+    voice: VoiceInput | undefined;
+    value: string;
+    setValue: (value: string) => void;
+    chatId: string;
+}
+export interface VoiceDictation {
+    /** Что отдать полю ввода скина; `undefined` — голоса нет. */
+    view: VoiceInputView | undefined;
+    /** Бросить идущую диктовку (при отправке): поздние слова в поле не попадут. Без диктовки ничего не делает. */
+    cancel: () => void;
+}
+/** Диктовка в поле ввода: состояние кнопки микрофона и запись слов в поле. */
+export declare function useVoiceDictation({ voice, value, setValue, chatId }: UseVoiceDictationOptions): VoiceDictation;

package/dist/types/voice-dialog.d.ts

@@ -0,0 +1,103 @@
+import type { AnswerStatus, VoiceCut, VoiceSound } from "./chat-types.js";
+/** Состояние голосового режима глазами человека. `interrupted` — человек только что перебил, агент замолчал. */
+export type VoiceDialogState = "off" | "connecting" | "listening" | "thinking" | "speaking" | "interrupted" | "error";
+/** Что пошло не так с режимом, в терминах человека; готовые надписи живут в словаре чата (`voiceDialog.errors`). */
+export type VoiceDialogError = "microphone_denied" | "microphone_missing" | "network" | "service_unavailable" | "recognition_lost" | "speech_unavailable" | "limit" | "rate_limited" | "idle" | "backgrounded";
+export interface VoiceDialogVoice {
+    id: string;
+    name: string;
+}
+/** Голосовой режим в поле ввода (договор скина, версия 10). */
+export interface VoiceDialogView {
+    state: VoiceDialogState;
+    error?: VoiceDialogError;
+    /** `false` — слушаем и пишем, но не озвучиваем. */
+    speechAvailable: boolean;
+    /** Нет или один голос — меню не показывать. */
+    voices?: VoiceDialogVoice[];
+    currentVoiceId?: string;
+    /** Громкость микрофона 0..1 для индикации. */
+    level?: number;
+    /** Включить или выключить режим. Вызывается из нажатия: браузер разрешает звук только так. */
+    onToggle: () => void;
+    onSelectVoice?: (id: string) => void;
+}
+/** Список голосов сервера и выбор человека; `persisted: false` — сервер выбор не запоминает. */
+export interface VoiceDialogVoices {
+    voices: VoiceDialogVoice[];
+    current: string;
+    persisted: boolean;
+}
+/** Приращение текста ответа агента, идущего сейчас. `partIndex` — номер текстовой части в `parts` сообщения. */
+export interface AssistantTextDelta {
+    messageId: string;
+    partIndex: number;
+    text: string;
+}
+/** Ответ агента закончился; `status` — чем именно (остановлен, ошибка и так далее). */
+export interface AnswerEnd {
+    messageId: string;
+    status: AnswerStatus;
+}
+/**
+ * Модель размышляет или вызывает инструмент: часть `reasoning` или `tool-*` ответа началась (`start`) или закончилась (`end`).
+ * Для `end` при ошибке инструмента и при конце ответа тоже приходит, так что пары всегда замкнуты.
+ */
+export interface AssistantActivity {
+    messageId: string;
+    /** Номер части в `parts` сообщения: по нему начало и конец сопоставляются. */
+    partIndex: number;
+    kind: "reasoning" | "tool";
+    /** Имя инструмента; только у `tool`. */
+    toolName?: string;
+    phase: "start" | "end";
+}
+/**
+ * Что движок режима знает о чате: отправить слова, остановить ответ и следить за текстом ответа.
+ * Настоящий мост делает хук `useVoiceDialog`; отправка идёт с признаком голосового режима (`voiceMode`).
+ */
+export interface DialogChatBridge {
+    /**
+     * Отправить слова агенту. Если отправить нельзя (пусто, ответ ещё идёт, чат не загружен),
+     * мост сообщает об этом через `subscribeAnswerEnd` как об ответе со статусом `error` и пустым `messageId`.
+     */
+    send(text: string, options?: {
+        sounds?: readonly VoiceSound[];
+    }): void;
+    /** Остановить идущий ответ; выполнено, когда ход остановлен. */
+    stop(): Promise<void>;
+    /**
+     * Склейка (`options.sounds` — звуки человека, ещё не отправленные модели): вместо последнего сообщения человека отправить `text` (прежние слова вместе с новыми) и остановить ход, у которого ещё нет
+     * ни текста, ни звука. Прежнего сообщения и пустого оборванного ответа в чате не остаётся, модель отвечает один раз.
+     * `true` — склеено, идёт ответ на `text`. `false` — не вышло (у ответа уже есть текст, сообщение набрано не голосом, сервер отказал):
+     * ход мог быть остановлен, текст не отправлен. Необязательный: мост без него — новые слова в ожидании ответа идут отдельным сообщением.
+     */
+    replaceLastMessage?(text: string, options?: {
+        sounds?: readonly VoiceSound[];
+    }): Promise<boolean>;
+    /** Приращения текста ответа. Возвращает отписку. */
+    subscribeAssistantText(listener: (delta: AssistantTextDelta) => void): () => void;
+    /** Конец ответа. Возвращает отписку. */
+    subscribeAnswerEnd(listener: (end: AnswerEnd) => void): () => void;
+    /**
+     * Размышление и вызовы инструментов: по ним голос говорит заполнители («Сейчас поищу…»). Необязательный: мост без него —
+     * режим работает, заполнителей нет. Возвращает отписку.
+     */
+    subscribeAssistantActivity?(listener: (activity: AssistantActivity) => void): () => void;
+    /** Показать отметку обрыва у ответа сразу, до записи на сервере (у хранилища может не быть `setVoiceCut`). */
+    showCut(messageId: string, cut: VoiceCut): void;
+}
+export interface VoiceDialogOpenOptions {
+    chatId: string;
+    chat: DialogChatBridge;
+    /** Вызывается при каждом изменении вида режима. */
+    onView(view: VoiceDialogView): void;
+}
+/** Голосовой режим для `AgentChat`; настоящий делает `createVoiceDialogEngine` из `@ykurilov/agent-chat-voice-dialog`. */
+export interface VoiceDialogEngine {
+    /** Включить режим. Звать внутри нажатия пользователя. Дальше состояние приходит через `onView`. */
+    open(options: VoiceDialogOpenOptions): void;
+    close(): void;
+    selectVoice(id: string): Promise<void>;
+    loadVoices(): Promise<VoiceDialogVoices>;
+}