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

package/dist/types/live-demos/live-demo-document.d.ts

@@ -0,0 +1,42 @@
+import type { LiveDemoColors } from "../skin-contract.js";
+/** Предел кода в байтах UTF-8: больше — показывается код, а не запуск. */
+export declare const MAX_LIVE_DEMO_BYTES: number;
+/** Выше рамка не бывает: сообщение с большей высотой не принимается. */
+export declare const MAX_LIVE_DEMO_HEIGHT = 10000;
+/** Песочница рамки: скрипты, и только. Без своего источника, окон, форм, диалогов и перехода страницы. */
+export declare const LIVE_DEMO_SANDBOX = "allow-scripts";
+/** Вид сообщения высоты из рамки. */
+export declare const LIVE_DEMO_HEIGHT_MESSAGE = "agent-chat-live-demo:height";
+/** Вид сообщения «код ушёл со своей страницы»: его шлёт только промежуточный документ, демонстрация погашена. */
+export declare const LIVE_DEMO_LEFT_MESSAGE = "agent-chat-live-demo:left";
+/** Кусок потока сервера: в чат попал чужой текст, демонстрации в нём больше не запускаются. */
+export declare const EXTERNAL_CONTENT_PART_TYPE = "data-external-content";
+/** Ничего по сети: скрипты и стили только встроенные, картинки, шрифты и медиа — из самого кода. */
+export declare const LIVE_DEMO_CSP: string;
+/**
+ * CSP промежуточного документа. Вложенный документ наследует его вдобавок к своему, поэтому картинки, шрифты, медиа и
+ * стили тут те же. Главное — `frame-src about:`: вложенная рамка не уйдёт ни на какой адрес, кроме `about:`.
+ */
+export declare const LIVE_DEMO_SHELL_CSP: string;
+/** Цвета, если скин своих не дал. */
+export declare const FALLBACK_DEMO_COLORS: Record<"light" | "dark", LiveDemoColors>;
+/**
+ * Документ внешней рамки для `srcdoc` — промежуточный: CSP с `frame-src about:`, свой скрипт и вложенная рамка, в
+ * которой `liveDemoInnerDocument`. Код модели этот документ не разбирает: он лежит строкой внутри скрипта.
+ */
+export declare function liveDemoDocument(source: string, colors: LiveDemoColors): string;
+/**
+ * Документ вложенной рамки: запрет искать адреса заранее, CSP, цвета темы CSS-переменными и свои скрипты — в `<head>`,
+ * код модели — в `<body>` без вложенных рамок и заблаговременных соединений. Документ модели целиком (`<html>`, `<head>`) парсер вливает в `<body>`: `<meta>`
+ * с CSP там не действует, поэтому ослабить политику код не может.
+ */
+export declare function liveDemoInnerDocument(source: string, colors: LiveDemoColors): string;
+/** Помещается ли код в предел `MAX_LIVE_DEMO_BYTES`. */
+export declare function liveDemoFits(source: string): boolean;
+/** Сообщение «код ушёл со своей страницы» — только от своей рамки. */
+export declare function demoLeftPage(event: Pick<MessageEvent, "data" | "source">, frameWindow: Window | null | undefined): boolean;
+/**
+ * Высота из сообщения рамки: только от её окна (`event.source`), только `{ type, height }` с конечным числом в пределах
+ * 1…`MAX_LIVE_DEMO_HEIGHT`, с округлением вверх. Иначе — `null`.
+ */
+export declare function demoHeightOf(event: Pick<MessageEvent, "data" | "source">, frameWindow: Window | null | undefined): number | null;

package/dist/types/live-demos/live-demo-frame.d.ts

@@ -0,0 +1,14 @@
+import type { LiveDemoColors } from "../skin-contract.js";
+export interface LiveDemoFrameProps {
+    source: string;
+    colors: LiveDemoColors;
+    /** Подпись рамки для диктора. */
+    title: string;
+    /** Код ушёл со своей страницы (сообщение промежуточного документа или вторая загрузка рамки). */
+    onLeftPage: () => void;
+}
+/**
+ * Рамка живой демонстрации: изолированная песочница, документ через `srcdoc`, ширина во весь ответ, высота — из
+ * сообщения своей рамки. Новые цвета — новый документ: демонстрация перерисовывается.
+ */
+export declare const LiveDemoFrame: import("react").MemoExoticComponent<({ source, colors, title, onLeftPage }: LiveDemoFrameProps) => import("react").JSX.Element>;

package/dist/types/live-demos/use-live-demo-blocks.d.ts

@@ -0,0 +1,18 @@
+import type { ChatSkin, LiveDemoColors, LiveDemoView } from "../skin-contract.js";
+/**
+ * Цвета демонстраций для текущей темы страницы: `skin.demoColors(dark)`, без него — свои. Смена темы даёт новые цвета,
+ * и демонстрации перерисовываются. `enabled: false` (демонстрации не подключены) — за темой не следит, `undefined`.
+ */
+export declare function useDemoColors(skin: ChatSkin, enabled: boolean): LiveDemoColors | undefined;
+/**
+ * Живые демонстрации одной текстовой части для скина (`AgentText.renderDemo`). Незакрытый блок, пока текст печатается,
+ * — `streaming`; закрытый запускается сразу, не дожидаясь конца ответа. Код не запускается, если он больше предела, не
+ * дописан к концу ответа, уже пытался уйти со своей страницы или в чате чужой текст (`blocked`: сервер сообщил, что в чат
+ * попали веб, файл или инструмент с пометкой). Нет цветов (демонстрации не подключены) — `undefined`.
+ */
+export declare function useLiveDemoBlocks({ markdown, streaming, colors, blocked }: {
+    markdown: string;
+    streaming: boolean;
+    colors: LiveDemoColors | undefined;
+    blocked: boolean;
+}): ((source: string, blockIndex: number) => LiveDemoView) | undefined;

package/dist/types/liveness/connection-errors.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Свои ошибки связи. Имя у них не `TypeError` и не `AbortError`: SDK чата принимает сетевой
+ * `TypeError` за «обрыв, можно продолжить с места» и удвоит части ответа, а `AbortError` — за «стоп».
+ */
+/** Сеть отказала, соединение оборвалось или вышел срок запроса. */
+export declare class ConnectionLostError extends Error {
+    constructor(message?: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Сервер слишком долго не присылал ни байта. */
+export declare class ConnectionSilentError extends Error {
+    constructor(silenceMs?: number);
+}
+export declare function isConnectionError(error: unknown): error is ConnectionLostError | ConnectionSilentError;

package/dist/types/liveness/reconnect-attempts.d.ts

@@ -0,0 +1,14 @@
+export declare const DEFAULT_RECONNECT_DELAYS_MS: readonly number[];
+export type ReconnectOutcome = "connected" | "exhausted" | "cancelled";
+export interface ReconnectAttemptsOptions {
+    /** Пауза перед каждой попыткой; сколько пауз — столько попыток. */
+    delaysMs: readonly number[];
+    /** Срок попытки целиком: история, заголовки потока и первый байт. */
+    attemptTimeoutMs: number;
+    /** Одна попытка: `true` — подключились. Её сигнал отменяется по сроку и при отмене серии. */
+    attempt: (signal: AbortSignal, index: number) => Promise<boolean>;
+    /** Отмена всей серии («стоп», уход со страницы). */
+    signal: AbortSignal;
+}
+/** Серия попыток переподключения с паузами и общим сроком на каждую попытку (research R10). */
+export declare function runReconnectAttempts(options: ReconnectAttemptsOptions): Promise<ReconnectOutcome>;

package/dist/types/liveness/request-deadline.d.ts

@@ -0,0 +1,16 @@
+import type { SilenceWatchOptions } from "./silence-watchdog.js";
+export interface DeadlineOptions {
+    /** Срок до заголовков ответа. */
+    timeoutMs: number;
+    /** Своя отмена (серия попыток): для SDK это обрыв связи, а не стоп собеседника. */
+    signal?: AbortSignal;
+    /** Срок покрывает и тело ответа: для запросов без потока. */
+    wholeBody?: boolean;
+    /** Следить за тишиной в теле потока; параметры строятся по ответу (например, по заголовку сервера). */
+    silence?: (response: Response) => Omit<SilenceWatchOptions, "translateError" | "onEnd">;
+}
+/**
+ * `fetch` со сроком. Сетевой `TypeError` и истёкший срок становятся `ConnectionLostError`.
+ * Отмена собеседником (`init.signal`) остаётся `AbortError`.
+ */
+export declare function fetchWithDeadline(fetchFn: (input: string, init?: RequestInit) => Promise<Response>, input: string, init: RequestInit | undefined, options: DeadlineOptions): Promise<Response>;

package/dist/types/liveness/silence-watchdog.d.ts

@@ -0,0 +1,21 @@
+/** Действующий срок тишины: не меньше трёх признаков жизни сервера (FR-017). */
+export declare function effectiveSilenceTimeoutMs(silenceTimeoutMs: number, heartbeatMs: number): number;
+export interface SilenceWatchOptions {
+    silenceTimeoutMs: number;
+    /** Срок до самого первого байта, если он короче: сервер шлёт пинг сразу после заголовков. */
+    firstByteTimeoutMs?: number;
+    onFirstByte?: () => void;
+    /** Тишина затянулась: закрыть исходное соединение и сообщить наверх. */
+    onSilence?: () => void;
+    /** Во что превратить ошибку чтения тела перед тем, как отдать её читателю. */
+    translateError?: (error: unknown) => unknown;
+    /** Тело закончилось любым способом: конец, ошибка, тишина или отмена читателем. */
+    onEnd?: () => void;
+}
+/**
+ * Пропускает тело ответа как есть (ошибки чтения — через `translateError`), но следит за временем последнего байта (любого, и пинга тоже).
+ * Тишина дольше срока — поток обрывается `ConnectionSilentError`, исходное соединение отменяется.
+ * Сравнение времён, а не «таймер на 30 с»: фоновая вкладка и сон телефона не рвут живой поток,
+ * а проснувшись — замечают тишину сразу (`visibilitychange`, `online`).
+ */
+export declare function watchSilence(body: ReadableStream<Uint8Array>, options: SilenceWatchOptions): ReadableStream<Uint8Array>;

package/dist/types/media-viewer/answer-file-images.d.ts

@@ -0,0 +1,18 @@
+import type { MessageAttachmentsView } from "../attachments-contract.js";
+import type { AgentChatMessage } from "../chat-types.js";
+import type { GeneratedImagesView } from "../skin-contract.js";
+/** Как показать часть `file` ответа агента: группой картинок или строкой со ссылкой на файл (текст ответа). */
+export type AnswerFileView = {
+    kind: "images";
+    view: GeneratedImagesView;
+} | {
+    kind: "file";
+    markdown: string;
+};
+/**
+ * Файлы в ответе агента (импорт переписки). Часть узнаётся по адресу (`MessageAttachmentItem.partUrl`), не по порядку.
+ * С `withImages` подряд идущие картинки — одна группа `GeneratedImages` на месте первой; ключ — номер части, `null` —
+ * часть уже в группе выше. Остальное (не картинка, неизвестная плагину часть, скин без `GeneratedImages`) — строкой
+ * «📎 имя» со ссылкой, если адрес известен: файл не пропадает молча.
+ */
+export declare function answerFileViews(message: AgentChatMessage, describe: ((message: AgentChatMessage) => MessageAttachmentsView | undefined) | undefined, withImages: boolean): Map<number, AnswerFileView | null>;

package/dist/types/media-viewer/collect-viewer-items.d.ts

@@ -0,0 +1,16 @@
+import type { MessageAttachmentsView } from "../attachments-contract.js";
+import type { AgentChatMessage } from "../chat-types.js";
+import type { MediaViewerItem } from "./media-viewer-types.js";
+export interface CollectViewerItemsInput {
+    /** Сообщения текущей ветки по порядку ленты. */
+    messages: readonly AgentChatMessage[];
+    /** `describe` плагина вложений; нет — у человека картинок нет. */
+    describeAttachments?: ((message: AgentChatMessage) => MessageAttachmentsView | undefined) | undefined;
+    /** Свои элементы сообщения (картинки агента): встают на место сообщения в ленте, после его вложений. */
+    extraItems?: ((message: AgentChatMessage) => readonly MediaViewerItem[]) | undefined;
+}
+/**
+ * Карусель окна просмотра: все картинки текущей ветки по порядку ленты. Одна картинка в нескольких сообщениях
+ * (то же вложение) — один элемент на первом месте: `key` по ней возвращает фокус и должен быть единственным.
+ */
+export declare function collectViewerItems({ messages, describeAttachments, extraItems }: CollectViewerItemsInput): MediaViewerItem[];

package/dist/types/media-viewer/generated-images.d.ts

@@ -0,0 +1,20 @@
+import type { DynamicToolUIPart, ToolUIPart } from "ai";
+import type { ImagesClient } from "../agent-chat-extensions.js";
+import type { AgentChatMessage } from "../chat-types.js";
+import type { GeneratedImagesView } from "../skin-contract.js";
+import type { MediaViewerItem } from "./media-viewer-types.js";
+/** Вид картинок агента для части ответа; `undefined` — это не вызов картинок, он остаётся строкой инструмента. */
+export type DescribeGeneratedImages = (part: ToolUIPart | DynamicToolUIPart) => GeneratedImagesView | undefined;
+/** `images` страницы — всегда списком: один клиент или несколько. */
+export declare const imageClientsOf: (images: ImagesClient | readonly ImagesClient[] | undefined) => readonly ImagesClient[];
+/**
+ * Картинки агента (`images` страницы): вызов инструмента одного из клиентов → вид для скина; клиент выбирается по имени
+ * инструмента. Нет `open` (у скина нет окна просмотра) — клик по картинке ничего не делает.
+ */
+export declare function describeGeneratedImages(images: ImagesClient | readonly ImagesClient[], call: {
+    api: string;
+    chatId: string;
+    open?: ((key: string, trigger: HTMLElement) => void) | undefined;
+}): DescribeGeneratedImages;
+/** Готовые картинки агента в сообщении — элементы карусели окна просмотра, по порядку частей. */
+export declare function generatedViewerItems(describe: DescribeGeneratedImages): (message: AgentChatMessage) => MediaViewerItem[];

package/dist/types/media-viewer/media-viewer-types.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Один элемент окна просмотра (договор скина, версия 13). `key` — id вложения или `<messageId>:<номер блока>` у схемы:
+ * по нему слой поведения возвращает фокус на элемент-источник.
+ */
+export type MediaViewerItem = {
+    kind: "image";
+    key: string;
+    src: string;
+    alt: string;
+    width?: number;
+    height?: number;
+} | {
+    kind: "diagram";
+    key: string;
+    svg: string;
+    source: string;
+};

package/dist/types/media-viewer/open-attachments.d.ts

@@ -0,0 +1,9 @@
+import type { MessageAttachmentsView } from "../attachments-contract.js";
+import type { AgentChatMessage } from "../chat-types.js";
+type DescribeAttachments = (message: AgentChatMessage) => MessageAttachmentsView | undefined;
+/**
+ * `describe` плагина вложений, у картинок которого есть `onOpen` (договор скина, версия 13): открыть в окне просмотра
+ * по id вложения. Нет `open` (у скина нет окна) — `describe` как есть, миниатюры как в 0.15.
+ */
+export declare function describeWithViewer(describe: DescribeAttachments | undefined, open: ((key: string, trigger: HTMLElement) => void) | undefined): DescribeAttachments | undefined;
+export {};

package/dist/types/media-viewer/use-media-viewer.d.ts

@@ -0,0 +1,23 @@
+import type { MediaViewerProps } from "../skin-contract.js";
+import type { MediaViewerItem } from "./media-viewer-types.js";
+export interface UseMediaViewerOptions {
+    /** Карусель чата на сейчас; зовётся, только пока окно открыто. Новая функция — карусель пересобирается. */
+    getItems: () => readonly MediaViewerItem[];
+    /** Смена значения (другой чат, другая ветка) закрывает окно. */
+    resetKey: string;
+}
+export interface MediaViewerController {
+    /**
+     * Открыть элемент `key`. `items` — свой набор (схема открывается одна); без него — карусель чата.
+     * Функция стабильна: строки ленты, которые её держат, не перерисовываются.
+     */
+    open: (key: string, trigger: HTMLElement, items?: readonly MediaViewerItem[]) => void;
+    /** Свойства для `skin.MediaViewer`; `null` — окно закрыто. */
+    viewer: MediaViewerProps | null;
+}
+/**
+ * Окно просмотра со стороны поведения: какой элемент открыт, запись в истории браузера (жест «назад» закрывает окно)
+ * и возврат фокуса на элемент, с которого открыли. Открытый элемент помнится по `key`: новые картинки в ленте
+ * окно не сдвигают, а пропавший элемент окно закрывает.
+ */
+export declare function useMediaViewer({ getItems, resetKey }: UseMediaViewerOptions): MediaViewerController;

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

@@ -0,0 +1,13 @@
+import type { MemorySkin } from "./memory-skin.js";
+import type { MemoryApi } from "./memory-types.js";
+export interface AgentMemoryProps {
+    /** Обмен с сервером: `createMemoryApi({ api: "/api/chat" })`. Создайте один раз — при смене объекта список грузится заново. */
+    api: MemoryApi;
+    /** Скин экрана памяти (договор 11), например `tandemMemorySkin`. */
+    skin: MemorySkin;
+}
+/**
+ * Экран памяти агента: записи по разделам, добавление, правка, удаление, «Стереть всю память» и блок «Объединено» с кнопкой «Вернуть как было».
+ * Всё видимое рисует скин; здесь — состояние, черновики и проверка ввода.
+ */
+export declare function AgentMemory({ api, skin }: AgentMemoryProps): import("react").JSX.Element;

package/dist/types/memory/memory-client.d.ts

@@ -0,0 +1,19 @@
+import type { MemoryApi } from "./memory-types.js";
+type Fetch = typeof globalThis.fetch;
+/** Сервер ответил отказом; `status` — код ответа, `kind` — `error.kind` из тела, если оно было (404 без тела — памяти нет). */
+export declare class MemoryRequestError extends Error {
+    readonly status: number;
+    readonly kind: string | undefined;
+    constructor(status: number, kind: string | undefined, action: string);
+}
+/**
+ * Клиент адресов памяти сервера: `GET/POST {api}/memory`, `PATCH/DELETE {api}/memory/{id}`, `DELETE {api}/memory`,
+ * склейки повторов — `GET {api}/memory/merges` и `POST {api}/memory/merges/{runId}/revert`.
+ * `api` — тот же адрес обработчика чата, например `/api/chat`. Вызывайте один раз (например, в `useMemo`):
+ * экран загружает список заново при смене объекта.
+ */
+export declare function createMemoryApi({ api, fetch: customFetch }: {
+    api: string;
+    fetch?: Fetch;
+}): MemoryApi;
+export {};

package/dist/types/memory/memory-skin.d.ts

@@ -0,0 +1,103 @@
+import type { ComponentType, ReactNode } from "react";
+import type { MemoryCounts, MemoryStatus } from "./memory-types.js";
+/** Ошибки полей формы записи готовыми надписями; `form` — отказ сервера или другое, что не про одно поле. */
+export interface MemoryNoteEditorErrors {
+    path?: string;
+    content?: string;
+    form?: string;
+}
+/** Что подтверждает окно: удаление одной записи или стирание всей памяти. */
+export type MemoryConfirmTarget = {
+    kind: "note";
+    content: string;
+} | {
+    kind: "all";
+    total: number;
+};
+/** Одна склейка для экрана: тексты записей «было» (скрытые оригиналы) и «стало» (результат в списке). */
+export interface MemoryMergeGroupView {
+    before: string[];
+    after: string;
+}
+/**
+ * Договор скина, версия 11: отдельный интерфейс для экрана памяти `AgentMemory` (договор чата `ChatSkin`
+ * и договор списка чатов `ChatListSkin` не менялись). Слой поведения решает, что показать, и хранит черновики; скин рисует
+ * готовые данные и зовёт колбэки. Надписи компоненты берут из `useChatLabels()`; ширина — любая, вплоть до телефона,
+ * без горизонтальной прокрутки.
+ */
+export interface MemorySkin {
+    /**
+     * Экран целиком: заголовок, счётчик, кнопки и состояния. `status`: `loading` и `error` (тогда `onRetry`) — записей нет,
+     * рисовать надпись состояния; `empty` — надпись «память пуста»; `unavailable` — памяти в приложении нет; `ready` — `children`.
+     * `counts` нет, пока список не загружен; если `shown < total` — показать подсказку `memoryShownHint`.
+     * Нет `onAdd` — форма новой записи уже открыта или памяти нет, кнопку не рисовать; нет `onClearAll` — стирать нечего.
+     * `error` — сообщение о том, что не вышло, готовой надписью (`role="alert"`). `newNoteEditor` — форма новой записи
+     * (над списком), `confirm` — окно подтверждения. `merges` — блок «Объединено» (карточки `MemoryMerge`); есть, только
+     * когда склейки есть; скин рисует его под списком записей со своим заголовком `memoryMergesHeading`.
+     */
+    MemoryScreen: ComponentType<{
+        status: MemoryStatus;
+        counts?: MemoryCounts;
+        onAdd?: () => void;
+        onClearAll?: () => void;
+        onRetry?: () => void;
+        error?: string;
+        newNoteEditor?: ReactNode;
+        merges?: ReactNode;
+        confirm?: ReactNode;
+        children: ReactNode;
+    }>;
+    /**
+     * Раздел дерева. `depth` — 0 для верхнего; `count` — записей в разделе, вместе с вложенными. В `children` сначала записи
+     * раздела, потом вложенные разделы.
+     */
+    MemoryGroup: ComponentType<{
+        name: string;
+        depth: number;
+        count: number;
+        children: ReactNode;
+    }>;
+    /** Запись. Нет обработчика — действие сейчас недоступно (идёт другое действие): кнопку показать неактивной. */
+    MemoryNoteRow: ComponentType<{
+        content: string;
+        onEdit?: () => void;
+        onDelete?: () => void;
+    }>;
+    /**
+     * Форма записи. Слой поведения хранит черновик: скин рисует поля с `path` (разделы через «/», например
+     * «О себе / Работа») и `content`. `canSave` — `false` для пустых полей; `pending` — запись уходит на сервер.
+     * Enter в поле раздела и кнопка «Сохранить» зовут `onSave`, Escape — `onCancel`.
+     */
+    MemoryNoteEditor: ComponentType<{
+        mode: "create" | "edit";
+        path: string;
+        content: string;
+        onPathChange: (value: string) => void;
+        onContentChange: (value: string) => void;
+        onSave: () => void;
+        onCancel: () => void;
+        canSave: boolean;
+        pending: boolean;
+        errors: MemoryNoteEditorErrors;
+    }>;
+    /**
+     * Одно слияние в блоке «Объединено»: для каждой склейки — «было» (тексты оригиналов) и «стало» (результат).
+     * `finishedAt` — время слияния (ISO 8601); человеку его показывает `labels.memoryMergeDate(new Date(finishedAt))`.
+     * `revertible: false` — записи с тех пор менялись, вернуть нельзя: кнопки нет, вместо неё `memoryMergeNotRevertible`.
+     * `revertible: true` и нет `onRevert` — идёт другое действие: кнопку «Вернуть как было» показать неактивной.
+     */
+    MemoryMerge: ComponentType<{
+        finishedAt: string;
+        groups: MemoryMergeGroupView[];
+        revertible: boolean;
+        onRevert?: () => void;
+    }>;
+    /** Подтверждение: удалить можно только через `onConfirm`. `error` — почему не вышло (окно остаётся, можно повторить). */
+    MemoryConfirm: ComponentType<{
+        target: MemoryConfirmTarget;
+        pending: boolean;
+        error?: string;
+        onConfirm: () => void;
+        onCancel: () => void;
+    }>;
+}

package/dist/types/memory/memory-tree.d.ts

@@ -0,0 +1,17 @@
+import type { MemoryNote } from "./memory-types.js";
+/** Раздел дерева: записи, лежащие прямо в нём, и вложенные разделы. */
+export interface MemoryTreeGroup {
+    name: string;
+    /** Путь от верхнего раздела, имена в нижнем регистре: годится в ключ. */
+    key: string;
+    notes: MemoryNote[];
+    groups: MemoryTreeGroup[];
+    /** Записей в разделе вместе с вложенными. */
+    count: number;
+}
+/**
+ * Раскладывает записи по разделам: запись с разделами `["О себе", "Работа"]` лежит в «Работа» внутри «О себе».
+ * Разделы, различающиеся только регистром, сливаются (имя берётся у первой записи); разделы идут по алфавиту,
+ * записи — в порядке списка.
+ */
+export declare function buildMemoryTree(notes: readonly MemoryNote[]): MemoryTreeGroup[];

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

@@ -0,0 +1,77 @@
+/** Запись памяти, как её отдаёт сервер (`GET {api}/memory`). Владельца в ответах нет. */
+export interface MemoryNote {
+    id: string;
+    /** Раздел записи от общего к частному: от 1 до 3 уровней. */
+    categories: string[];
+    content: string;
+    /** Замок: правка и удаление называют версию, которую человек видел. */
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/** То, что человек вводит: разделы и текст. */
+export interface MemoryNoteInput {
+    categories: string[];
+    content: string;
+}
+export interface MemoryCounts {
+    /** Записей всего. */
+    total: number;
+    /** Предел записей. */
+    limit: number;
+    /** Сколько записей видит агент в каждом запросе (остальные он находит поиском). */
+    shown: number;
+}
+/** Одна склейка повторов: `originals` («было») заменены записью `result` («стало»). */
+export interface MemoryMergeGroup {
+    result: MemoryNote;
+    originals: MemoryNote[];
+}
+/** Слияние одного запуска оптимизации (`GET {api}/memory/merges`), новейшие первыми. */
+export interface MemoryMerge {
+    runId: string;
+    /** Время в формате ISO 8601. */
+    finishedAt: string;
+    /** Можно ли «Вернуть как было»: результаты склеек с тех пор не менялись. */
+    revertible: boolean;
+    groups: MemoryMergeGroup[];
+}
+/**
+ * Обмен с сервером памяти. Каждый метод при отказе бросает `MemoryRequestError`
+ * (обрыв связи — обычная ошибка `fetch`). `createMemoryApi` строит его по адресам `{api}/memory`.
+ */
+export interface MemoryApi {
+    list(): Promise<{
+        notes: MemoryNote[];
+        counts: MemoryCounts;
+    }>;
+    create(input: MemoryNoteInput): Promise<MemoryNote>;
+    update(id: string, version: number, input: MemoryNoteInput): Promise<MemoryNote>;
+    remove(id: string, version: number): Promise<void>;
+    /** Стирает всю память человека; возвращает, сколько записей удалено. */
+    clear(): Promise<number>;
+    /** Склейки повторов, которые можно показать и вернуть. */
+    listMerges(): Promise<MemoryMerge[]>;
+    /** Возвращает слияние как было. Отказ 409: `conflict` — результат с тех пор менялся; `limit_reached` — памяти не хватит места; `duplicate` — запись, что вернулась бы, уже добавлена заново. */
+    revertMerge(runId: string): Promise<void>;
+}
+/** Что пошло не так с действием: коды сервера (`conflict` — слияние вернуть нельзя) плюс `unavailable` (памяти нет) и `other` (сбой, обрыв связи). */
+export type MemoryFailure = "not_found" | "stale_version" | "limit_reached" | "duplicate" | "invalid" | "conflict" | "unavailable" | "other";
+/** Итог действия. Отказ — не исключение: скину нужна надпись, а не стек. */
+export type MemoryActionResult = {
+    ok: true;
+} | {
+    ok: false;
+    failure: MemoryFailure;
+};
+/**
+ * Состояние экрана: `loading` — грузится; `ready` — записи есть; `empty` — записей нет; `unavailable` — сервер ответил
+ * 404 (память в приложении не включена); `error` — список не загрузился.
+ */
+export type MemoryStatus = "loading" | "ready" | "empty" | "unavailable" | "error";
+/** Форма записи (как у пакета памяти): до 3 разделов по 60 знаков, текст до 500. Экран проверяет её до отправки. */
+export declare const memoryNoteLimits: {
+    readonly maxCategories: 3;
+    readonly maxCategoryChars: 60;
+    readonly maxContentChars: 500;
+};

package/dist/types/memory/use-memory-notes.d.ts

@@ -0,0 +1,23 @@
+import type { MemoryActionResult, MemoryApi, MemoryCounts, MemoryFailure, MemoryMerge, MemoryNote, MemoryNoteInput, MemoryStatus } from "./memory-types.js";
+export interface MemoryNotesState {
+    state: MemoryStatus;
+    /** Записи в порядке сервера: новейшие первыми. */
+    notes: MemoryNote[];
+    /** `null`, пока список не загружен. */
+    counts: MemoryCounts | null;
+    /** Склейки повторов, новейшие первыми; пусто, если их нет или сервер их не отдаёт. */
+    merges: MemoryMerge[];
+    /** Как закончилось последнее действие, если отказом; следующее действие сбрасывает. */
+    error: MemoryFailure | null;
+    add(input: MemoryNoteInput): Promise<MemoryActionResult>;
+    /** Уходит версия записи из списка. Конфликт версий: список перезагружен, вызывающий держит свои значения и может повторить. */
+    edit(id: string, input: MemoryNoteInput): Promise<MemoryActionResult>;
+    remove(id: string): Promise<MemoryActionResult>;
+    clear(): Promise<MemoryActionResult>;
+    /** «Вернуть как было»: оригиналы возвращаются вместо результата, список записей и склеек загружается заново. */
+    revertMerge(runId: string): Promise<MemoryActionResult>;
+    /** Загружает список заново: после отказа — с экраном загрузки, иначе тихо. */
+    reload(): void;
+}
+/** Состояние экрана памяти: загрузка, добавление, правка, удаление, стирание. Ничего не рисует. */
+export declare function useMemoryNotes(api: MemoryApi): MemoryNotesState;

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

@@ -0,0 +1,45 @@
+import type { ReactNode } from "react";
+import type { AgentChatMessage, AnswerStatus } from "./chat-types.js";
+/** Ответ, под которым решается, показывать ли кнопку. */
+export interface MessageActionTarget {
+    message: AgentChatMessage;
+    /** Итог ответа: пока ответ пишется, кнопок нет, и `visible` не зовётся. */
+    status: Exclude<AnswerStatus, "streaming">;
+    /** Последний ответ ветки. */
+    last: boolean;
+}
+/** Что получает обработчик кнопки. */
+export interface MessageActionContext {
+    chatId: string;
+    /** Id ответа — тот же, что в истории на сервере и в `onTurnFinished`. */
+    messageId: string;
+    message: AgentChatMessage;
+    /** Текст ответа, как его копирует «Скопировать». */
+    text: string;
+}
+/**
+ * Своя кнопка приложения под ответом агента. Иконку даёт приложение готовым элементом (`<Heart />`): слой поведения и
+ * скин дизайн-систему приложения не знают. Массив кнопок держите постоянным (вне компонента или в `useMemo`):
+ * новый массив на каждой отрисовке перерисовывает все ответы ленты.
+ */
+export interface MessageAction {
+    /** Постоянный и уникальный среди кнопок. */
+    id: string;
+    /** Подпись: текст кнопки или подсказка и `aria-label` у кнопки с одной иконкой. */
+    label: string;
+    icon?: ReactNode;
+    /** Показывать ли кнопку у этого ответа. Нет — у каждого законченного ответа. */
+    visible?: (target: MessageActionTarget) => boolean;
+    /** Пока обещание не выполнено, кнопка «занята». Ошибка уходит в консоль, а не в чат. */
+    onRun: (context: MessageActionContext) => void | Promise<void>;
+}
+/** Id кнопок, чьи обработчики ещё идут, по id ответа. Список ответа меняется, только когда меняются его кнопки. */
+export type RunningMessageActions = ReadonlyMap<string, readonly string[]>;
+/**
+ * Запуск своих кнопок ответа: двойное нажатие не запускает обработчик второй раз, пока первый идёт; сбой обработчика
+ * уходит в консоль.
+ */
+export declare function useMessageActionRuns(chatId: string): {
+    running: RunningMessageActions;
+    run: (action: MessageAction, message: AgentChatMessage, text: string) => void;
+};

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

@@ -0,0 +1,27 @@
+import type { ReactElement, Ref, RefObject } from "react";
+import type { AgentChatMessage } from "./chat-types.js";
+export interface MessageFeedHandle {
+    /** Ставит прилипание и ведёт ленту вниз: после отправки сообщения. */
+    scrollToBottom: () => void;
+}
+export interface MessageFeedProps {
+    /** Скроллер скина: элемент, который прокручивается. */
+    scrollRef: RefObject<HTMLElement | null>;
+    messages: AgentChatMessage[];
+    renderMessage: (message: AgentChatMessage, index: number) => ReactElement;
+    /** Пока идёт ответ, последнее сообщение остаётся в дереве, даже если окно ленты уехало вверх. */
+    keepLastMounted: boolean;
+    /** Что показать при первом показе: сообщение с этим id встаёт у верха; по умолчанию лента внизу. */
+    openAtMessageId?: string;
+    ref?: Ref<MessageFeedHandle>;
+}
+/**
+ * Лента сообщений окном: в дереве только сообщения у экрана и небольшой запас. Правило
+ * прокрутки живёт здесь, а не в скине: при первом показе истории лента внизу, у низа она едет
+ * за растущим ответом, а после шага читателя вверх (колесо, касание, клавиша) стоит на месте.
+ * Снова прилипает, когда читатель вернулся к низу ближе чем на 96 px.
+ */
+declare function MessageFeedView({ scrollRef, messages, renderMessage, keepLastMounted, openAtMessageId, ref }: MessageFeedProps): import("react").JSX.Element;
+/** `memo`: ввод в поле и другие перерисовки чата, не меняющие ленту, её не трогают. */
+export declare const MessageFeed: import("react").MemoExoticComponent<typeof MessageFeedView>;
+export {};