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

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

@@ -0,0 +1,103 @@
+import type { AgentChatMessage, ChatModelChoice } from "./chat-types.js";
+import type { AgentChatExtensions } from "./agent-chat-extensions.js";
+import type { AnswerEditing } from "./answer-editing/answer-editing.js";
+import type { AttachmentsPlugin } from "./attachments-contract.js";
+import type { ChatSkin } from "./skin-contract.js";
+import type { VoiceInput } from "./voice-input.js";
+import type { VoiceDialogEngine } from "./voice-dialog.js";
+import type { AppRefusal } from "./app-refusal.js";
+import type { ChatAccess } from "./chat-access.js";
+import type { LivenessOptions } from "./use-agent-chat.js";
+import type { AgentAppBridge } from "./app-bridge/app-bridge.js";
+import type { MessageAction } from "./message-actions.js";
+import type { ComposerActions } from "./composer-actions.js";
+import type { AppEventHandler } from "./app-events.js";
+import type { TurnFinishedEvent } from "./turn-finished.js";
+import type { ChatStateValues } from "./chat-state/chat-state.js";
+export interface AgentChatProps extends AgentChatExtensions {
+    /** Адрес обработчика чата, например `/api/chat`. */
+    api: string;
+    /** Какой чат открыть. Нужен ровно один из `chatId` и `subject`: оба сразу или ни одного — ошибка разработчика (исключение). */
+    chatId?: string;
+    /**
+     * Ключ объекта приложения (урок, заказ), например `"lesson:42"`: при открытии чат спрашивает у сервера
+     * `POST {api}/subject` чат человека по этому ключу (нет — сервер создаёт, с приветствием) и дальше работает с ним как
+     * с обычным. Отказ сервера показывается текстом. Нужен `subjectChats` в обработчике чата.
+     */
+    subject?: string;
+    skin: ChatSkin;
+    /** Сроки живой связи; по умолчанию как в договоре 002. */
+    liveness?: LivenessOptions;
+    /** Голосовой ввод; без него кнопки микрофона в поле ввода нет. */
+    voice?: VoiceInput;
+    /** Голосовой режим («разговор»): `createVoiceDialogEngine` из `@ykurilov/agent-chat-voice-dialog`. Без него кнопки режима нет. */
+    voiceDialog?: VoiceDialogEngine;
+    /** Вложения к сообщениям: `attachmentsClient` из `@ykurilov/agent-chat-attachments/react`. Нет — чат только текстовый. */
+    attachments?: AttachmentsPlugin;
+    /** У сервера включены лимиты расходов (`limits` в обработчике чата): показывать предупреждение и исчерпание. */
+    spendingLimits?: boolean;
+    /** Чат занят (идёт ответ) или свободен; вызывается при открытии чата и при каждой смене. Для расширений вокруг чата, например списка чатов. */
+    onBusyChange?: (busy: boolean) => void;
+    /** Связь с приложением (место на экране, изменения данных, браузерные инструменты); её создаёт `AgentPanelProvider`. Нет — чат как раньше. */
+    appBridge?: AgentAppBridge;
+    /** Текст в поле ввода при открытии чата. */
+    initialDraft?: string;
+    /** Правка ответов агента (песочница): кнопка правки у законченных ответов, отметки «изменено», редактор страницы. Нет — ответы не правятся. */
+    answerEditing?: AnswerEditing;
+    /** Сообщения текущей ветки и занятость чата; вызывается при каждой смене. Для панелей рядом с чатом, например журнала песочницы. */
+    onFeedChange?: (feed: {
+        messages: AgentChatMessage[];
+        busy: boolean;
+    }) => void;
+    /** Свои кнопки под ответами агента («Нравится», «В заметки»): рисует скин в ряду действий ответа. Массив держите постоянным. */
+    messageActions?: MessageAction[];
+    /** Ход закончен: у ответа `messageId` итог `status` (включая остановку и ошибку). Один раз на ход; открытие чата хода не даёт. */
+    onTurnFinished?: (turn: TurnFinishedEvent) => void;
+    /** Свои кнопки у поля ввода («Проверить работу»): узел или функция от помощника (`ComposerHelper`: поле, `send`, `addFiles`). Нет — кнопок нет. */
+    composerActions?: ComposerActions;
+    /**
+     * События приложения (`afterTurn`, `emitAppEvent`, `publishAppEvent` на сервере): по разу на событие. `live: true` —
+     * пришло живьём (во время хода или вне хода через канал наблюдения), `false` — лежало в истории при открытии чата.
+     * У события вне хода нет `messageId`. Вид события в ответе задаёт `appEvents`.
+     */
+    onAppEvent?: AppEventHandler;
+    /**
+     * Приложение отказало ходу (`beforeTurn`) или человеку в доступе (`resolveUser`): `kind` — `turn_refused` или `access_refused`,
+     * `code` — для программы, `message` — слова для человека (до 300 знаков; чат их уже показал). Зовётся на каждый такой отказ,
+     * в том числе когда сервер не открыл чат объекта (`subject`).
+     */
+    onTurnRefused?: (refusal: AppRefusal) => void;
+    /**
+     * Права человека в чате и закрытие (`closed`, `null` — открыт): после загрузки истории и при каждой смене (отказ
+     * `chat_closed`, закрытие инструментом, события `chat-closed` и `chat-reopened`). Кнопки чат прячет сам.
+     */
+    onChatAccessChange?: (access: ChatAccess) => void;
+    /**
+     * Состояние чата показанной ветки (`model.state` на сервере) после загрузки истории и при каждой смене: запись по
+     * ходу ответа, смена ветки, правка. То же значение повторно не приходит. Внутри ленты — `useChatState()`.
+     */
+    onStateChange?: (state: ChatStateValues) => void;
+    /**
+     * Человек выбрал модель или уровень рассуждений в меню, и сервер сохранил выбор. Выбор по умолчанию и выбор из истории
+     * его не зовут. На сервере то же сообщает хук `onModelChosen`.
+     */
+    onModelChosen?: (choice: ChatModelChoice) => void;
+    /**
+     * Служебный, для `ChatWorkspace`: приложению не нужен. Чат не открылся и прав не будет: его нет, приложение не пустило
+     * человека или история не загрузилась. Пока права неизвестны, список чатов скрыт, а в этих случаях он нужен,
+     * чтобы выбрать другой чат.
+     */
+    onChatUnavailable?: () => void;
+    /**
+     * Другое значение — история перечитывается с сервера: права, закрытие и лента. Для случая, когда чат изменили не
+     * через этот экран (например, песочница открыла закрытый чат снова). Первое значение ничего не перечитывает.
+     */
+    reloadKey?: number;
+    /**
+     * Поправки на лету: пока идёт ответ, поле принимает текст, агент учтёт его на ближайшем шаге. Включено, если скин их
+     * рисует (`ChatSkin.steering`, договор 21); `false` — выключить и у такого скина. Скин без `steering` — как до 0.34.
+     */
+    steering?: boolean;
+}
+/** Лента чата с агентом. Всё видимое рисуют компоненты скина. */
+export declare function AgentChat(props: AgentChatProps): import("react").JSX.Element;

package/dist/types/agent-panel/agent-panel-hooks.d.ts

@@ -0,0 +1,14 @@
+import type { AppDataChange, ScreenPlace } from "../app-bridge/app-bridge.js";
+import type { AgentPanelControls } from "./panel-context.js";
+export type { AgentPanelControls } from "./panel-context.js";
+/** Управление панелью из кода приложения: открыть, закрыть, открыть чат, новый чат с готовым текстом, отступ для `push`. */
+export declare function useAgentPanel(): AgentPanelControls;
+/**
+ * Где сейчас человек: место уходит с каждым запросом хода, пока компонент на экране. Главнее место компонента, который
+ * появился на экране позже; вложенный всегда главнее внешнего (страница главнее макета, в котором стоит), и при первом
+ * показе, и после переходов. Смена места не меняет, чьё главнее. `null` или размонтирование снимает только это место —
+ * снова действует место другого компонента.
+ */
+export declare function useAgentPlace(place: ScreenPlace | null): void;
+/** Подписка на изменения данных по метке (или списку меток). Подписчик зовётся один раз на сообщение, всегда свежий. */
+export declare function useAgentDataChanges(tag: string | readonly string[], handler: (change: AppDataChange) => void): void;

package/dist/types/agent-panel/agent-panel-provider.d.ts

@@ -0,0 +1,24 @@
+import type { ReactNode } from "react";
+import type { AppDataChange, BrowserToolFunction } from "../app-bridge/app-bridge.js";
+export interface AgentPanelProviderProps {
+    /** Адрес обработчика чата, например `/api/chat`. */
+    api: string;
+    /** Номер человека в приложении: открыта ли панель и какой чат открыт, помнится отдельно для каждого. Смена — состояние другого человека. */
+    userKey: string;
+    /** Функции браузерных инструментов по именам (описания задаёт сервер в `agent.browserTools`). */
+    browserTools?: Record<string, BrowserToolFunction>;
+    /** `overlay` — панель поверх страницы, `push` — приложение сдвигает страницу на `pageInset`. По умолчанию `overlay`. */
+    mode?: "overlay" | "push";
+    /** Ширина панели на широком экране, px. По умолчанию 420. */
+    width?: number;
+    /** Каждое сообщение об изменении данных, любой метки. */
+    onDataChanged?: (change: AppDataChange) => void;
+    /** Свой `fetch` для списка чатов. Сам чат, как и `AgentChat`, ходит через `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+    children?: ReactNode;
+}
+/**
+ * Состояние панели агента и связь чата с приложением. Ставится в корневой макет, над маршрутами:
+ * панель, открытый чат и идущий ответ живут при переходах по страницам приложения.
+ */
+export declare function AgentPanelProvider({ api, userKey, browserTools, mode, width, onDataChanged, fetch, children }: AgentPanelProviderProps): import("react").JSX.Element;

package/dist/types/agent-panel/agent-panel-skin.d.ts

@@ -0,0 +1,41 @@
+import type { ComponentType, ReactNode, Ref } from "react";
+/**
+ * Договор скина, версия 12: отдельный интерфейс для боковой панели агента (`AgentPanel` из `@ykurilov/agent-chat-react/panel`).
+ * `ChatSkin`, `ChatListSkin` (версия 7) и `MemorySkin` (версия 11) не менялись. Скин без `AgentPanelSkin` работает как раньше,
+ * но для панели не годится (ошибка типов). Надписи компоненты берут из `useChatLabels()`.
+ */
+export interface AgentPanelSkin {
+    /** Кнопка агента в углу страницы. Положение и вид — дело скина. */
+    AgentPanelLauncher: ComponentType<{
+        open: boolean;
+        /** Идёт ответ в открытом чате: показать значок. */
+        busy: boolean;
+        onToggle: () => void;
+        /** Сюда слой поведения возвращает фокус при закрытии. */
+        buttonRef: Ref<HTMLButtonElement>;
+    }>;
+    /**
+     * Рамка панели. Смонтирована всегда; закрытая — скрыта (`hidden`/`inert`), содержимое живёт.
+     * Страница под панелью не затемняется и остаётся кликабельной. При переходе `open: false → true` фокус уходит в поле ввода внутри рамки;
+     * роль `complementary` или `dialog` без `aria-modal`, `aria-label` из словаря. На экране ≤ 640 px панель на весь экран,
+     * «Закрыть» всегда видна, горизонтальной прокрутки нет.
+     */
+    AgentPanel: ComponentType<{
+        open: boolean;
+        mode: "overlay" | "push";
+        /** Ширина на широком экране, px. */
+        width: number;
+        /** Название открытого чата (или «Новый чат»). */
+        title: string;
+        /** Список открыт поверх чата. */
+        listOpen: boolean;
+        onListOpenChange: (open: boolean) => void;
+        onClose: () => void;
+        /** Esc внутри панели. Слой поведения сам решает: закрыть список или панель. Список закрылся и фокус пропал — верните его в поле ввода. */
+        onEscape: () => void;
+        /** Открытый чат (`AgentChat`). */
+        children: ReactNode;
+        /** Список чатов (`skin.ChatList`); рисовать поверх чата, когда `listOpen`. */
+        list: ReactNode;
+    }>;
+}

package/dist/types/agent-panel/agent-panel.d.ts

@@ -0,0 +1,13 @@
+import type { AgentChatProps } from "../agent-chat.js";
+import type { ChatListSkin } from "../chat-list/chat-list-skin.js";
+import type { ChatSkin } from "../skin-contract.js";
+import type { AgentPanelSkin } from "./agent-panel-skin.js";
+export interface AgentPanelProps extends Omit<AgentChatProps, "api" | "chatId" | "subject" | "skin" | "onBusyChange" | "appBridge" | "initialDraft"> {
+    /** Скин чата, списка и панели (например, `tandemSkin`). */
+    skin: ChatSkin & ChatListSkin & AgentPanelSkin;
+}
+/**
+ * Кнопка агента и панель с открытым чатом и списком чатов поверх него. Всё видимое рисует скин.
+ * Открытый чат смонтирован и при закрытой панели: ответ идёт, подписчики на изменения данных слышат его.
+ */
+export declare function AgentPanel({ skin, ...chatProps }: AgentPanelProps): import("react").JSX.Element;

package/dist/types/agent-panel/index.d.ts

@@ -0,0 +1,8 @@
+export { AgentPanelProvider } from "./agent-panel-provider.js";
+export type { AgentPanelProviderProps } from "./agent-panel-provider.js";
+export { AgentPanel } from "./agent-panel.js";
+export type { AgentPanelProps } from "./agent-panel.js";
+export { useAgentDataChanges, useAgentPanel, useAgentPlace } from "./agent-panel-hooks.js";
+export type { AgentPanelControls } from "./agent-panel-hooks.js";
+export type { AgentPanelSkin } from "./agent-panel-skin.js";
+export type { AgentAppBridge, AppDataChange, BrowserCall, BrowserCallResult, BrowserToolFunction, BrowserToolImplementations, ScreenPlace, } from "../app-bridge/app-bridge.js";

package/dist/types/agent-panel/panel-context.d.ts

@@ -0,0 +1,46 @@
+import type { RefObject } from "react";
+import type { AppBridgeControl } from "../app-bridge/create-app-bridge.js";
+import type { ChatListState } from "../chat-list/use-chat-list.js";
+/** Управление панелью из кода приложения (`useAgentPanel`). */
+export interface AgentPanelControls {
+    open: boolean;
+    setOpen(open: boolean): void;
+    toggle(): void;
+    /** Открыть панель на чате; чужой или удалённый — «Чат не найден», список — по кнопке «Чаты». */
+    openChat(chatId: string): void;
+    /** Новый (или пустой) чат и готовый текст в поле ввода. `false` — не создался (список открыт с ошибкой). */
+    openNewChat(options?: {
+        draft?: string;
+    }): Promise<boolean>;
+    /** Отступ справа для страницы в режиме `push`; 0 — закрыто, режим `overlay` или экран ≤ 640 px. */
+    pageInset: number;
+    mode: "overlay" | "push";
+    width: number;
+    /** Идёт ответ в открытом чате — для значка на кнопке. */
+    busy: boolean;
+}
+/** То, что нужно `AgentPanel`, чтобы нарисовать кнопку, рамку, список и открытый чат. */
+export interface PanelView {
+    api: string;
+    controls: AgentPanelControls;
+    list: ChatListState;
+    listOpen: boolean;
+    setListOpen(open: boolean): void;
+    /** Список выбран или создан: закрыть его. */
+    closeList(): void;
+    /** Esc внутри панели: открыт список — закрыть его, иначе закрыть панель; при подтверждении удаления — ничего. */
+    escape(): void;
+    /** Ключ открытого чата: меняется вместе с чатом и с новым готовым текстом. */
+    chatKey: string;
+    initialDraft: string | undefined;
+    setBusy(busy: boolean): void;
+    launcherRef: RefObject<HTMLButtonElement | null>;
+    bridge: AppBridgeControl["bridge"];
+}
+export declare const AppBridgeContext: import("react").Context<AppBridgeControl | null>;
+export declare const PanelControlsContext: import("react").Context<AgentPanelControls | null>;
+export declare const PanelViewContext: import("react").Context<PanelView | null>;
+/** Мост и регистрация мест и подписок; для хуков панели. */
+export declare function useAppBridgeControl(user?: string): AppBridgeControl;
+export declare function usePanelControls(user: string): AgentPanelControls;
+export declare function usePanelView(user: string): PanelView;

package/dist/types/agent-panel/panel-state.d.ts

@@ -0,0 +1,12 @@
+/** Под этим ключом `localStorage` помнит, открыта ли панель: `{ "open": boolean }`. */
+export declare const panelOpenKey: (api: string, userKey: string) => string;
+/** Под этим ключом `useChatList` помнит чат, открытый в панели у этого человека. */
+export declare const panelChatKey: (api: string, userKey: string) => string;
+/** Была ли панель открыта у этого человека. Нет записи, битая запись или хранилище недоступно — закрыта. */
+export declare function readPanelOpen(api: string, userKey: string): boolean;
+export declare function rememberPanelOpen(api: string, userKey: string, open: boolean): void;
+/**
+ * Открыта ли панель у этого человека; смена `api` или `userKey` — его запомненное состояние.
+ * При отрисовке на сервере и в первом проходе гидратации — закрыта, потом — запомненное: разметка не расходится.
+ */
+export declare function usePanelOpen(api: string, userKey: string): [boolean, (open: boolean) => void];

package/dist/types/answer-editing/answer-editing.d.ts

@@ -0,0 +1,25 @@
+import type { ReactNode } from "react";
+import type { AgentChatMessage } from "../chat-types.js";
+/** Что в ответе изменено человеком: текст и (или) результаты вызовов инструментов. */
+export interface AnswerEditMark {
+    textEdited: boolean;
+    editedToolCallIds: string[];
+}
+/** Что получает редактор ответа, который рисует страница. */
+export interface AnswerEditorSlot {
+    message: AgentChatMessage;
+    /** Сервер принял правку и создал ответ `newMessageId`: чат переходит на его ветку и закрывает редактор. */
+    onSaved: (newMessageId: string) => void;
+    onCancel: () => void;
+}
+/**
+ * Правка ответов агента (песочница). Чат даёт законченным ответам кнопку правки, показывает
+ * отметки «изменено» и ставит редактор страницы на место ответа. Без этого свойства ответы не правятся.
+ */
+export interface AnswerEditing {
+    /** Отметки правок по id ответа. */
+    edits: ReadonlyMap<string, AnswerEditMark>;
+    renderEditor: (slot: AnswerEditorSlot) => ReactNode;
+}
+/** Изменён ли ответ человеком хоть в чём-то. */
+export declare function answerEdited(mark: AnswerEditMark | undefined): boolean;

package/dist/types/app-bridge/app-bridge.d.ts

@@ -0,0 +1,50 @@
+import type { InferToolInput, ToolSet } from "ai";
+/** Где сейчас человек в приложении. Форма совпадает с `ScreenPlace` из `@ykurilov/agent-chat-core`: ядро браузеру не нужно. */
+export interface ScreenPlace {
+    description: string;
+    data?: Record<string, unknown>;
+}
+/** Сообщение «данные приложения изменены»; `id` один на сообщение, повторы с тем же `id` игнорируются. */
+export interface AppDataChange {
+    id: string;
+    tag: string;
+    details?: unknown;
+}
+/** Тип куска потока ответа «данные изменены»; совпадает с `APP_CHANGE_PART_TYPE` ядра. */
+export declare const APP_CHANGE_PART_TYPE = "data-app-change";
+/** Вызов браузерного инструмента, который сервер просит выполнить на этой вкладке. */
+export interface BrowserCall {
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+}
+/** Итог вызова: результат или текст ошибки для модели. */
+export type BrowserCallResult = {
+    output: unknown;
+} | {
+    error: string;
+};
+/** Функция браузерного инструмента: делает действие на странице. `signal` обрывает её (срок вышел, «стоп»). */
+export type BrowserToolFunction<Input = any> = (input: Input, context: {
+    signal: AbortSignal;
+}) => unknown;
+/**
+ * Функции браузерных инструментов по именам. С описаниями из общего модуля (`tool({ description, inputSchema })`)
+ * вход каждой функции выводится из схемы: `BrowserToolImplementations<typeof browserToolDescriptions>`.
+ */
+export type BrowserToolImplementations<Descriptions extends ToolSet = ToolSet> = {
+    [Name in keyof Descriptions]: BrowserToolFunction<InferToolInput<Descriptions[Name]>>;
+};
+/** Связь чата с приложением: место на экране, номер вкладки, сообщения об изменении данных, браузерные вызовы. */
+export interface AgentAppBridge {
+    /** Номер вкладки; сервер по нему отдаёт браузерные вызовы той вкладке, где идёт ответ. */
+    tabId: string;
+    /** Место на момент запроса; `null` — места нет. */
+    currentPlace(): ScreenPlace | null;
+    /** Раздаёт сообщение подписчикам; повтор `id` игнорирует. */
+    dataChanged(change: AppDataChange): void;
+    /** Исполняет функцию приложения по имени с `signal`; нет функции — `{ error: "Инструмент недоступен на этой странице" }`, брошенная ошибка — `{ error: её текст }`. */
+    browserCall(call: BrowserCall, options?: {
+        signal?: AbortSignal;
+    }): Promise<BrowserCallResult>;
+}

package/dist/types/app-bridge/browser-calls.d.ts

@@ -0,0 +1,24 @@
+import type { AgentAppBridge, BrowserCall } from "./app-bridge.js";
+/** Тип куска потока ответа «выполни браузерный инструмент»; совпадает с `BROWSER_CALL_PART_TYPE` ядра. */
+export declare const BROWSER_CALL_PART_TYPE = "data-browser-call";
+/**
+ * Под этим ключом `sessionStorage` хранит исполненные на вкладке вызовы (адрес чата и номер вызова, как ключ ожидания на
+ * сервере): повтор кусков после перезагрузки их не повторит, а тот же номер в другом чате исполнится.
+ */
+export declare const BROWSER_CALLS_DONE_KEY = "agent-chat:browser-calls-done";
+/** Данные куска `data-browser-call`: вызов и вкладка, которой он адресован. */
+export interface BrowserCallRequest extends BrowserCall {
+    tabId: string;
+}
+/**
+ * Исполняет вызов из потока ответа, если он адресован этой вкладке и ещё не исполнялся, и отправляет итог на
+ * `{chatUrl}/browser-tools/{toolCallId}`. Сбой связи — тихо, вызов на сервере закроется сам. `409` (срок вышел, ход
+ * кончился) — тоже без ошибки, но сервер уже ушёл дальше: `onNotPending` даёт ленте перечитать историю.
+ */
+export declare function runBrowserCall(call: BrowserCallRequest, context: {
+    bridge: AgentAppBridge;
+    chatUrl: string;
+    request: (input: string, init?: RequestInit) => Promise<Response>;
+    signal: AbortSignal;
+    onNotPending?: () => void;
+}): Promise<void>;

package/dist/types/app-bridge/create-app-bridge.d.ts

@@ -0,0 +1,35 @@
+import type { AgentAppBridge, AppDataChange, BrowserToolFunction, ScreenPlace } from "./app-bridge.js";
+/** Что мост берёт у приложения; читается в момент вызова, поэтому новые свойства провайдера видны без нового моста. */
+export interface AppBridgeOptions {
+    /** Функции браузерных инструментов по именам. */
+    browserTools?: Record<string, BrowserToolFunction>;
+    /** Получает каждое сообщение об изменении данных, любой метки. */
+    onDataChanged?: (change: AppDataChange) => void;
+    /** Ответ модели, если функции инструмента на этой странице нет. */
+    toolUnavailableMessage: string;
+}
+/** Владелец места: чем больше `order`, тем позже создан и тем главнее его место. */
+export interface PlaceOwner {
+    readonly order: number;
+}
+/** Мост и то, чем его наполняют хуки панели: места компонентов и подписки на изменения данных. */
+export interface AppBridgeControl {
+    bridge: AgentAppBridge;
+    /**
+     * Владелец места для одного компонента; создаётся при его первой отрисовке. Владелец, созданный позже, главнее:
+     * вложенный компонент рисуется после внешнего, поэтому страница всегда главнее макета, в котором стоит.
+     */
+    createPlaceOwner(): PlaceOwner;
+    /** Место компонента `owner`; смена места не меняет, чьё главнее. `null` — снять своё место. */
+    setPlace(owner: PlaceOwner, place: ScreenPlace | null): void;
+    /** Снимает только место `owner`; места других компонентов остаются. */
+    removePlace(owner: PlaceOwner): void;
+    /** Подписка на сообщения с одной из меток `tags`; возвращает отписку. */
+    subscribe(tags: readonly string[], handler: (change: AppDataChange) => void): () => void;
+}
+/**
+ * Под этим ключом `sessionStorage` хранит `id` розданных сообщений (последние 500): повтор кусков ответа, в том числе
+ * после перезагрузки страницы во время ответа, не раздаёт сообщение второй раз.
+ */
+export declare const APP_CHANGES_DELIVERED_KEY = "agent-chat:app-changes-delivered";
+export declare function createAppBridge(readOptions: () => AppBridgeOptions): AppBridgeControl;

package/dist/types/app-bridge/remembered-ids.d.ts

@@ -0,0 +1,6 @@
+/** Последние id, которые помнит вкладка: в `sessionStorage` под `key` (переживают перезагрузку), без хранилища — на время жизни страницы. */
+export interface RememberedIds {
+    /** Отмечает id; `false` — он уже отмечен. */
+    claim(id: string): boolean;
+}
+export declare function rememberedIds(key: string, limit: number): RememberedIds;

package/dist/types/app-bridge/tab-id.d.ts

@@ -0,0 +1,10 @@
+/** Под этим ключом `sessionStorage` хранит номер вкладки: переживает перезагрузку, у новой вкладки свой. */
+export declare const TAB_ID_KEY = "agent-chat:tab-id";
+/**
+ * Под ключом `agent-chat:tab-open:{номер}` `localStorage` отмечает, что страница с этим номером открыта; уходя (`pagehide`),
+ * страница снимает отметку. «Дублировать вкладку» копирует `sessionStorage` вместе с номером, но исходная вкладка ещё открыта —
+ * дубликат видит отметку и берёт себе новый номер. Иначе обе вкладки исполнили бы один браузерный вызов.
+ */
+export declare const tabOpenKey: (tabId: string) => string;
+/** Номер этой вкладки: прочитанный из `sessionStorage`, если другая открытая вкладка его не занимает, иначе новый случайный. */
+export declare function readTabId(): string;

package/dist/types/app-events.d.ts

@@ -0,0 +1,39 @@
+import type { ComponentType } from "react";
+import type { AgentChatMessage } from "./chat-types.js";
+/** Событие приложения в ответе агента. Форма совпадает с `AppEvent` из `@ykurilov/agent-chat-core`: ядро браузеру не нужно. */
+export interface AppEvent {
+    type: string;
+    data?: unknown;
+}
+/** Где и когда событие пришло: `live` — живьём (поток ответа или канал наблюдения), а не из истории. */
+export interface AppEventInfo {
+    live: boolean;
+    /** Ответ агента с событием; у события вне хода (`publishAppEvent`) его нет. */
+    messageId?: string;
+}
+/**
+ * Свой вид событий приложения внутри ответа: тип события → компонент («урок зачтён» — плашка). Рисуется прямо в теле
+ * ответа, там, где лежит часть события, как виджеты: отдельного слота скина нет. Тип без компонента не виден.
+ */
+export type AppEventViews = Record<string, ComponentType<{
+    event: AppEvent;
+    messageId: string;
+}>>;
+export type AppEventHandler = (event: AppEvent, info: AppEventInfo) => void;
+/** Событие из присланного сервером значения; не событие — `undefined`. */
+export declare function appEventOf(value: unknown): AppEvent | undefined;
+/** Событие из части ответа; часть не событие или битая — `undefined`. */
+export declare function appEventOfPart(part: AgentChatMessage["parts"][number]): AppEvent | undefined;
+/** Учёт событий в ответах ленты. */
+export interface AppEventReport {
+    /** Новые события ответа `messageId` придут живьём, с перечитанной историей (хук итога, доделанный после «Стопа»). */
+    expectLive(messageId: string): void;
+}
+/**
+ * Зовёт `onAppEvent` по разу на каждое событие в ответах ленты. События, что лежали в истории при открытии чата или
+ * пришли с перечитанной историей, когда чат свободен (смена ветки), — `live: false`; пришедшие, пока идёт ход, и
+ * ожидаемые (`expectLive`) — `live: true`. Скопированные из прежнего ответа («Повторить», `id` вида `copied:…`) — всегда
+ * `live: false`: они уже сработали там. Повторная загрузка тех же ответов событие второй раз не даёт; смена чата
+ * начинает счёт заново (`AgentChat` к тому же пересоздаёт ленту на каждый чат).
+ */
+export declare function useAppEventReport(chatId: string, loaded: boolean, busy: boolean, messages: readonly AgentChatMessage[], onAppEvent: AppEventHandler | undefined): AppEventReport;

package/dist/types/app-refusal.d.ts

@@ -0,0 +1,21 @@
+/** Длиннее экран не показывает: текст отказа — короткая причина, а не страница. */
+export declare const SERVER_REFUSAL_MAX_LENGTH = 300;
+/**
+ * Чей отказ: `turn_refused` — приложение не пустило ход (`beforeTurn`), `access_refused` — не пустило человека
+ * (`resolveUser`), `chat_closed` — чат закрыт, `action_forbidden` — действие запрещено правами чата (`code` — право),
+ * `chat_creation_refused` — приложение не дало создать новый чат («Новый чат» в списке).
+ */
+export type AppRefusalKind = "turn_refused" | "access_refused" | "chat_closed" | "action_forbidden" | "chat_creation_refused";
+/** Отказ приложения: код для программы и слова для человека (до 300 знаков). */
+export interface AppRefusal {
+    kind: AppRefusalKind;
+    code: string;
+    message: string;
+}
+/**
+ * Отказ приложения из тела ответа: `{ error: { kind, code, message } }`, `kind` — один из `AppRefusalKind`.
+ * Статус не важен (403 или 401): вид и слова в теле главнее. `null` — тело другое, без кода или без слов.
+ */
+export declare function appRefusalOf(response: Response): Promise<AppRefusal | null>;
+/** Слова отказа в одну строку, не длиннее `SERVER_REFUSAL_MAX_LENGTH`. */
+export declare function shortenedRefusalText(text: string): string;

package/dist/types/attachments-contract.d.ts

@@ -0,0 +1,82 @@
+import type { FileUIPart } from "ai";
+import type { AgentChatMessage } from "./chat-types.js";
+/** Файл в поле ввода до отправки. */
+export interface ComposerAttachmentItem {
+    id: string;
+    name: string;
+    kind: "image" | "file";
+    /** Адрес для миниатюры картинки (локальный, пока файл не отправлен). */
+    previewUrl?: string;
+    status: "uploading" | "ready" | "error";
+}
+/** Вложения в поле ввода (договор скина, версия 5): скрепка, перетаскивание, вставка, превью с удалением. */
+export interface ComposerAttachments {
+    items: ComposerAttachmentItem[];
+    /** Выбранные, перетащенные или вставленные файлы. */
+    onAddFiles: (files: File[]) => void;
+    onRemove: (id: string) => void;
+    /** Значение для `accept` поля выбора файла. */
+    accept: string;
+    /** Что сказать человеку до отправки, готовой надписью: отказ по файлу, лимит, «модель не видит картинки». */
+    notice?: string;
+}
+/** Вложение в ленте у сообщения человека. */
+export interface MessageAttachmentItem {
+    id: string;
+    /**
+     * Адрес части `file` сообщения, из которой этот элемент (`attachment:…`). По нему файл в ответе агента встаёт на место
+     * своей части. Нет — в ответе агента элемент не узнаётся, часть показывается ссылкой без адреса.
+     */
+    partUrl?: string;
+    name: string;
+    kind: "image" | "file";
+    /** Адрес файла на сервере: миниатюра картинки или ссылка на скачивание. */
+    url: string;
+    mediaType: string;
+    /** Подпись, если нужна (например, «PDF»). */
+    caption?: string;
+    /**
+     * Открыть картинку в окне просмотра (версия 13). Есть только у картинки, когда у скина есть `MediaViewer`:
+     * миниатюру сделать кнопкой с подписью `labels.images.open`. Нет — миниатюра как раньше.
+     */
+    onOpen?: (trigger: HTMLElement) => void;
+}
+/** Вложения сообщения для ленты (договор скина, версия 5). */
+export interface MessageAttachmentsView {
+    /** Подпись группы для экранного диктора. */
+    label: string;
+    items: MessageAttachmentItem[];
+}
+/** Состояние вложений в открытом чате: его ведёт плагин, слой поведения только связывает с полем ввода и лентой. */
+export interface AttachmentsController {
+    composer: ComposerAttachments;
+    /** Все файлы загружены без ошибок и вложений не больше допустимого: можно отправлять. */
+    ready: boolean;
+    /** В поле ввода есть хотя бы один файл. */
+    hasFiles: boolean;
+    /** Готовые файлы для отправки; поле не трогает. */
+    readFiles: () => FileUIPart[];
+    /**
+     * Файлы ушли с сообщением: поле очищается, но файлы помнятся, пока их можно вернуть (`restoreFiles`).
+     * Следующая отправка забывает прежние.
+     */
+    markSent: () => void;
+    /**
+     * Сервер не принял сообщение: помнящиеся файлы возвращаются в поле. `kind` — причина от сервера; если файл
+     * устарел и удалён, он возвращается с пометкой «загрузите снова».
+     */
+    restoreFiles: (kind: string | undefined) => void;
+    /** Вложения сообщения для ленты; `undefined` — у сообщения нет файлов. Функция стабильна, пока чат тот же. */
+    describe: (message: AgentChatMessage) => MessageAttachmentsView | undefined;
+}
+/** Расширение вложений для `AgentChat` (пакет `@ykurilov/agent-chat-attachments/react`). */
+export interface AttachmentsPlugin {
+    /** Хук: вызывается один раз за отрисовку, всегда в одном и том же порядке. */
+    useController: (input: {
+        api: string;
+        chatId: string;
+        /** Видит ли выбранная модель картинки; `undefined` — пока неизвестно. */
+        modelSeesImages: boolean | undefined;
+        fetch?: typeof globalThis.fetch;
+    }) => AttachmentsController;
+}