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

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

@@ -0,0 +1,235 @@
+import type { AfterTurnHandler, ModelChosenHandler, RecoverInterruptedAnswersOptions, ReplyChecksSetting, StateChangedHandler, AgentSettings, BackgroundTasks, BeforeTurnHandler, Chat, BeforeCreateChatHandler, ChatCapabilitiesHandler, ChatErrorKind, ChatService, ChatStorage, CompactionSettings, FlushOptions, MessageAttachments, ModelCatalog, ModelChoice, ResolvedUser, SpendingLimits, StaffActor, ChatInstructions, TurnFinishedHandler, TurnNotStartedHandler, TurnObserver } from "@ykurilov/agent-chat-core";
+import type { ChatMemory } from "./memory-routes.js";
+import type { NewChatDataResolver } from "./new-chat-data.js";
+import type { SubjectChatsResolver } from "./subject-chat-route.js";
+export type { ChatMemory, MemoryCounts, MemoryMergeRecord, MemoryResult } from "./memory-routes.js";
+/**
+ * `busy` — в чате идёт ход; `approval_not_pending` — на этот запрос подтверждения отвечать уже нечем (решён или закрыт новым сообщением);
+ * `approval_stale` — фоновая задача ждёт ответа уже на другой вопрос: ответ на старый не принят;
+ * `not_pending` — браузерный вызов не ждёт ответа этой вкладки (уже отвечен, срок вышел, ход кончился, вкладка чужая);
+ * `widget_not_pending` — виджет не ждёт ответа (уже отвечен, закрыт сообщением, в другой ветке, убран из настроек);
+ * `invalid_answer` — ответ на виджет не прошёл схему, длиннее предела или тело запроса негодное; ничего не записано;
+ * `widget_answer_refused` — приложение отказало в ответе на виджет (`checkAnswer`): `{ kind, code, message }`, ничего не записано,
+ * виджет ждёт;
+ * `widget_answer_cancelled` — человек нажал «Стоп», пока шла проверка ответа (`checkAnswer`): `{ kind, code, message }`, ничего не
+ * записано, виджет ждёт; это не сбой;
+ * `widget_check_timeout` (504) — проверка ответа (`checkAnswer`) не уложилась в `checkAnswerTimeoutMs`: `{ kind, code, message }`,
+ * ничего не записано, виджет ждёт, повторить можно;
+ * `too_many_turns` — у человека уже идёт столько ответов, сколько разрешено (`maxConcurrentTurnsPerUser`);
+ * `forbidden_origin` — запрос, меняющий данные, пришёл с чужой страницы (`allowedOrigins`); `too_large` — тело больше 1 МиБ;
+ * `turn_refused` — приложение отказало в ходе (`beforeTurn`); `access_refused` — приложение отказало в доступе (`resolveUser`);
+ * `action_forbidden` — действие запрещено правами чата (`chatCapabilities`); `chat_closed` — чат закрыт (`closeChat`);
+ * `chat_creation_refused` — приложение не дало завести новый чат (`beforeCreateChat`).
+ * У отказов приложения одно тело: `{ kind, code, message }` (у `action_forbidden` ещё `action`).
+ */
+export type HandlerErrorKind = ChatErrorKind | "not_found" | "busy" | "invalid" | "spending_limit_reached" | "approval_not_pending" | "approval_stale" | "widget_not_pending" | "invalid_answer" | "widget_answer_refused" | "widget_answer_cancelled" | "widget_check_timeout" | "not_pending" | "too_many_turns" | "forbidden_origin" | "too_large" | "turn_refused" | "access_refused" | "action_forbidden" | "chat_closed" | "chat_creation_refused";
+/** Вложения: приём в сообщение и сборка запроса (для ядра) плюс адреса под `/:chatId/attachments`. Даёт пакет `@ykurilov/agent-chat-attachments`. */
+export interface ChatAttachments extends MessageAttachments {
+    /** Ответ на `GET {base}/attachments/settings`. */
+    settings(): Response;
+    /** Всё под `/:chatId/attachments`; чат уже проверен как принадлежащий человеку. `segments` — путь после `attachments`. */
+    handle(input: {
+        request: Request;
+        userId: string;
+        chatId: string;
+        segments: string[];
+    }): Promise<Response>;
+}
+export interface ChatHandlerOptions {
+    /** Путь, под которым смонтирован обработчик, например `/api/chat`. */
+    basePath: string;
+    storage: ChatStorage;
+    /**
+     * Кто спрашивает: `{ id }` — человек, `null` — не вошёл (401 `invalid`). `{ refused: { code, message, status? } }` —
+     * приложение отказывает человеку в доступе своими словами: на любом адресе ответ `status` (401 или 403, по умолчанию 403)
+     * `{ error: { kind: "access_refused", code, message } }`. Код — `[a-z0-9_.-]`, 1–64 знака (иначе 500 `other` и строка
+     * в `logError`); текст — до 300 знаков.
+     */
+    resolveUser: (request: Request) => Promise<ResolvedUser>;
+    /** Выбор модели для новых чатов. Не задан — первая модель каталога у первого провайдера с ключом. */
+    defaultChoice?: ModelChoice;
+    catalog: ModelCatalog;
+    agent: AgentSettings;
+    /** Автосжатие истории: включено по умолчанию, `false` выключает. Подробнее — в настройках ядра. */
+    compaction?: CompactionSettings | false;
+    /** Вложения к сообщениям. Не заданы — адресов `/attachments` нет, сообщения только текстовые. */
+    attachments?: ChatAttachments;
+    /**
+     * Лимиты расходов (пакет `@ykurilov/agent-chat-limits`). Исчерпанный лимит — ответ 429 `spending_limit_reached`
+     * на отправку, повтор, переделку и правку; появляется адрес `GET {base}/:chatId/spending`. Не заданы — адреса нет.
+     */
+    limits?: SpendingLimits;
+    /**
+     * Сколько ответов одного человека могут идти одновременно во всех его чатах. Сверх этого — ответ 429
+     * `too_many_turns` с полем `limit`, ничего не записано. Считается в памяти процесса. По умолчанию 3; `Infinity` — без предела.
+     */
+    maxConcurrentTurnsPerUser?: number;
+    /**
+     * Проверка приложения перед ходом: вернуть `{ code, message }` — ход не начнётся, ничего не запишется, ответ 403
+     * `{ error: { kind: "turn_refused", code, message } }` на отправку, повтор, переделку, правку, ответ на подтверждение
+     * и ответ на виджет. Подробнее — `ChatServiceOptions.beforeTurn`. Нет — ходы не проверяются.
+     */
+    beforeTurn?: BeforeTurnHandler;
+    /**
+     * Ход не начался, хотя `beforeTurn` его пропустил (чат занят, предел ходов, лимит, повтор id, неверный запрос, сбой):
+     * снять резерв приложения. Ответ клиенту прежний. Подробнее — `ChatServiceOptions.turnNotStarted`.
+     */
+    turnNotStarted?: TurnNotStartedHandler;
+    /**
+     * Права человека в чате: частичный список `{ право: boolean }`, пропущенное — `true`. Запрещённое — 403
+     * `{ error: { kind: "action_forbidden", action, code, message } }`, история отдаёт `capabilities`, экран прячет кнопки.
+     * Право `attachments` закрывает и загрузку вложений (`/:chatId/attachments`, кроме GET). Подробнее —
+     * `ChatServiceOptions.chatCapabilities`. Нет — всё разрешено.
+     */
+    chatCapabilities?: ChatCapabilitiesHandler;
+    /**
+     * Можно ли человеку завести новый чат (`POST {base}`; тот же хук спрашивают мессенджеры на `/new`). Отказ — 403
+     * `{ error: { kind: "chat_creation_refused", code, message } }`, чат не создан. Подробнее —
+     * `ChatServiceOptions.beforeCreateChat`. Нет — чаты заводятся без проверки.
+     */
+    beforeCreateChat?: BeforeCreateChatHandler;
+    /**
+     * Долгая память агента между чатами (пакет `@ykurilov/agent-chat-memory`): ядро добавляет её в запросы и инструменты,
+     * появляются адреса `{base}/memory` для экрана памяти. Не задана — адресов нет (404), чат как раньше.
+     */
+    memory?: ChatMemory;
+    /**
+     * Список чатов человека: `GET {base}`, переименование `PATCH {base}/{id}` и удаление `DELETE {base}/{id}`.
+     * Не включён — этих адресов нет (404), у приложения с одним чатом всё работает как раньше. Чаты объектов
+     * (`subjectChats`) в списке не видны; `{ subjectChats: true }` — видны, с полем `subjectKey`.
+     */
+    chatList?: boolean | {
+        subjectChats?: boolean;
+    };
+    /**
+     * Чаты объектов приложения (урок, заказ): адрес `POST {base}/subject { key }` → `{ id, created }` находит или
+     * создаёт чат человека по ключу (1–200 знаков). Приложение по ключу отдаёт данные объекта (только для сервера),
+     * название и приветствие нового чата — или отказ `{ code, message }` (ответ 403 `turn_refused`, чат не создан).
+     * Не задано — адреса нет (404). Требует хранилища с `findChatBySubject`: без него — ошибка при создании обработчика.
+     */
+    subjectChats?: SubjectChatsResolver;
+    /**
+     * Данные нового чата, который человек создаёт из браузера (`POST {base}`): сервер решает, что записать, браузер
+     * данных не присылает. JSON-объект до 16 КБ (`Chat.data`) или `undefined` — чат без данных. Видят `beforeTurn`,
+     * `chatInstructions`, инструменты (`model.chat.data`) и `afterTurn` (`turn.chatData`); в браузер не уходят.
+     * Вернул не объект или бросил — ответ 500, чат не создан. Чаты объектов (`subjectChats`) берут данные из своего решения.
+     * Требует хранилища с `updateChatData`: без него — ошибка при создании обработчика.
+     */
+    newChatData?: NewChatDataResolver;
+    /**
+     * Чужие страницы, которым можно менять данные чата с куками человека, например `["https://school.getcourse.ru"]`,
+     * когда чат встроен в чужой сайт и шлёт запросы прямо оттуда. Свою страницу вносить не нужно: запросы с неё проходят всегда.
+     * Запрос, меняющий данные (не GET), с чужой страницы — ответ 403 `forbidden_origin`, ничего не записано.
+     * Запросы не из браузера (без заголовков Origin и Sec-Fetch-Site) проходят: их судит `resolveUser`.
+     */
+    allowedOrigins?: string[];
+    /** Откуда брать ключи провайдеров. По умолчанию `process.env`. */
+    env?: Record<string, string | undefined>;
+    /** Журнал сервера: нет ключа провайдера, непредвиденные сбои. По умолчанию `console.error`. */
+    logError?: (message: string) => void;
+    /** Промежуток между признаками жизни в потоках ответа. По умолчанию 10 000 мс, не меньше 1000. */
+    heartbeatIntervalMs?: number;
+    /** Наблюдатель хода (песочница): см. `ChatServiceOptions.turnObserver`. Нет — запрос к модели побайтно прежний. */
+    turnObserver?: TurnObserver;
+    /** Своя инструкция чата (песочница): см. `ChatServiceOptions.chatInstructions`. `null` — инструкция приложения. */
+    chatInstructions?: ChatInstructions;
+    /** Сотрудник хода по чату (песочница: копия чата человека): см. `ChatServiceOptions.staffOfChat`. */
+    staffOfChat?: (chat: Chat) => StaffActor | null | undefined;
+    /** Инструменты, чей результат правка ответа не меняет (файлы): см. `ChatServiceOptions.lockedToolOutputs`. */
+    lockedToolOutputs?: readonly string[];
+    /**
+     * Фоновые задачи (пакет `@ykurilov/agent-chat-background`): появляются адреса `{base}/:chatId/tasks`. Не заданы —
+     * адресов задач нет (404), запрос к модели прежний.
+     */
+    background?: BackgroundTasks;
+    /**
+     * Ход закончен: `{ userId, chatId, messageId, status, modelId, providerId }`, один раз на ход при любом итоге —
+     * законченном, остановленном, с ошибкой, прерванном, ждущем человека. Зовётся, когда итог уже записан; ход обработчик
+     * не ждёт, его сбой уходит в `logError`. Нет — ничего не зовётся.
+     */
+    onTurnFinished?: TurnFinishedHandler;
+    /**
+     * Итог хода для приложения: ход ждёт его до `finish`, возвращённые `events` ложатся в ответ частями `data-app-event`.
+     * Повторы, срок, состояние в ответе и доделка после перезапуска — как у `ChatServiceOptions.afterTurn`. Событие вне
+     * хода — `service.publishAppEvent` (служба из `createChatServer`): открытая вкладка получит его через `watch`.
+     */
+    afterTurn?: AfterTurnHandler;
+    /** Срок хука итога на все попытки, мс. По умолчанию 30 000. */
+    afterTurnTimeoutMs?: number;
+    /** Попыток хука итога. По умолчанию 3. */
+    afterTurnAttempts?: number;
+    /**
+     * Состояние чата сменилось (ход, правка, «Переделать», «Повторить», выбор ветки, правка ответа): копия состояния в
+     * таблицах приложения. Как у `ChatServiceOptions.onStateChanged`; открытая вкладка получает событие `state-changed`
+     * через `watch`.
+     */
+    onStateChanged?: StateChangedHandler;
+    /** Срок хука смены состояния на все попытки, мс. По умолчанию 30 000. */
+    onStateChangedTimeoutMs?: number;
+    /** Попыток хука смены состояния. По умолчанию 3. */
+    onStateChangedAttempts?: number;
+    /**
+     * Человек выбрал модель или уровень в меню (`PUT {chat}/model`): после записи выбора. Подстановка выбора и
+     * `service.setModel(..., { by: "app" })` его не зовут. Как у `ChatServiceOptions.onModelChosen`.
+     */
+    onModelChosen?: ModelChosenHandler;
+    /**
+     * Видит ли человек `GET …/models`: `false` — 403 `action_forbidden` (`action: "modelDetails"`). Меню не знает чата,
+     * поэтому право `modelDetails` его не закрывает. Нет — меню видно всем. Как у `ChatServiceOptions.modelMenu`.
+     */
+    modelMenu?: (input: {
+        userId: string;
+    }) => boolean | Promise<boolean>;
+    /**
+     * Закрытые верхние ключи состояния чата: не уходят в браузер ни в истории, ни в потоке хода, ни в `state-changed`
+     * адреса `watch`. Сервер видит их как обычно. Как у `ChatServiceOptions.privateStateKeys`.
+     */
+    privateStateKeys?: readonly string[];
+    /** Проверки готового ответа перед записью. Как у `ChatServiceOptions.replyChecks`. */
+    replyChecks?: ReplyChecksSetting;
+    /** Часы службы: тесты и песочница подменяют время целиком. Как у `ChatServiceOptions.now`. */
+    now?: () => Date;
+}
+export interface ChatHandler {
+    basePath: string;
+    fetch(request: Request): Promise<Response>;
+    /**
+     * Помечает «прерванными» ответы, оборванные прошлым запуском сервера, и запускает регулярную проверку брошенных
+     * ответов. Вызывать при старте, до приёма запросов; в Next.js — один раз сразу после `createChatHandler`: свои
+     * живые ответы проверка не трогает. Без вызова оборванные ответы остаются «идущими». Возвращает число помеченных.
+     * `{ soleServer: true }` — копия сервера на этой базе одна: оборванные ответы прерываются сразу, а не через 15–20 с.
+     * Только при старте процесса: вызов позже прервёт ход, который как раз запускается. Нельзя с несколькими копиями
+     * сервера на одной базе и с несколькими обработчиками в одном процессе (dev-режим Next.js): прервутся живые ответы.
+     */
+    recoverInterruptedAnswers(options?: RecoverInterruptedAnswersOptions): Promise<number>;
+    /**
+     * Штатная остановка: после того как сервер перестал принимать запросы, до закрытия хранилища. Ждёт идущие ответы до
+     * `waitForAnswersMs` (по умолчанию 0), не успевшие останавливает, как «Стоп», с записью; возвращается, когда всё
+     * записано и хуки итога закончены. Подробнее — `ChatService.flush`.
+     */
+    flush(options?: FlushOptions): Promise<void>;
+    /**
+     * Открыт ли у чата этого владельца поток `GET /:chatId/watch` (вкладка с чатом). Необязателен: обёртки над сервером
+     * (песочница) реализуют этот тип без него; мессенджеры берут его у `ChatServerService`.
+     */
+    hasWatchers?(ownerId: string, chatId: string): boolean;
+}
+/** Служба чата сервера: служба ядра плюс то, что знает только сервер, — открытые вкладки и задачи фона. */
+export interface ChatServerService extends ChatService {
+    /** Открыт ли у чата этого владельца поток `GET /:chatId/watch`. */
+    hasWatchers(ownerId: string, chatId: string): boolean;
+    /** Задачи фона; нет фона — нет и этого поля. */
+    tasks?: {
+        list: BackgroundTasks["listForChat"];
+    } & Pick<BackgroundTasks, "cancel" | "answerApproval">;
+}
+/** HTTP-обработчик чата на стандартных `Request`/`Response` (contracts/http-api.md). */
+export declare function createChatHandler(options: ChatHandlerOptions): ChatHandler;
+/**
+ * Обработчик чата и его служба: приложению (песочнице) служба нужна для своих адресов поверх тех же чатов —
+ * в одном процессе с обработчиком, с общим реестром идущих ответов.
+ */
+export declare function createChatServer(options: ChatHandlerOptions): {
+    handler: ChatHandler;
+    service: ChatServerService;
+};

package/dist/types/heartbeat.d.ts

@@ -0,0 +1,15 @@
+/** Заголовок, по которому вкладка узнаёт, как часто сервер шлёт признак жизни. */
+export declare const HEARTBEAT_HEADER = "x-agent-chat-heartbeat-ms";
+export declare const MIN_HEARTBEAT_INTERVAL_MS = 1000;
+export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 10000;
+/**
+ * Ответ-поток из частей UI-сообщения с признаком жизни: SSE-комментарий `: ping` сразу и потом
+ * каждые `heartbeatIntervalMs`. События приходят целиком (по одному на кусок), а пинг встаёт
+ * только между ними. Клиент SDK комментарии пропускает, поэтому в сообщения и хранилище они
+ * не попадают.
+ */
+export declare function createHeartbeatResponse(options: {
+    stream: ReadableStream<unknown>;
+    heartbeatIntervalMs: number;
+}): Response;
+export declare function assertHeartbeatInterval(heartbeatIntervalMs: number): void;

package/dist/types/hono.d.ts

@@ -0,0 +1,4 @@
+import type { Hono } from "hono";
+import type { ChatHandler } from "./chat-handler.js";
+/** Монтирует обработчик чата (или расширения с такой же формой: `basePath` и `fetch`, например голоса) в приложение Hono по его `basePath`. */
+export declare function mountChat(app: Hono<any, any, any>, handler: Pick<ChatHandler, "basePath" | "fetch">): void;

package/dist/types/index.d.ts

@@ -0,0 +1,6 @@
+export { createChatHandler, createChatServer } from "./chat-handler.js";
+export type { ChatAttachments, ChatHandler, ChatHandlerOptions, ChatServerService, HandlerErrorKind } from "./chat-handler.js";
+export type { AccessRefusal, ResolvedUser } from "@ykurilov/agent-chat-core";
+export { accessRefusedResponse, allowedUser } from "@ykurilov/agent-chat-core";
+export { turnRefusalResponse } from "./subject-chat-route.js";
+export type { SubjectChatSettings, SubjectChatsResolver } from "./subject-chat-route.js";

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

@@ -0,0 +1,53 @@
+import type { LongTermMemory, MemoryError, MemoryMergeRevertResult, MemoryNote } from "@ykurilov/agent-chat-core";
+/** Исход действия с памятью: запись или ошибка-ответ. То же, что у пакета `@ykurilov/agent-chat-memory`. */
+export type MemoryResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: MemoryError;
+};
+/** Сколько записей человека, какой предел и сколько из них агент видит в каждом запросе. */
+export interface MemoryCounts {
+    total: number;
+    limit: number;
+    shown: number;
+}
+/** Слияние одного запуска: что стало (`result`) вместо каких записей (`originals`). Как у пакета `@ykurilov/agent-chat-memory`. */
+export interface MemoryMergeRecord {
+    runId: string;
+    finishedAt: string;
+    revertible: boolean;
+    groups: {
+        result: MemoryNote;
+        originals: MemoryNote[];
+    }[];
+}
+/**
+ * Долгая память вместе с действиями для адресов `/memory`. Даёт пакет `@ykurilov/agent-chat-memory`.
+ * `listMerges` и `revertMerge` есть не у всякой памяти: без них адреса `/memory/merges` отвечают 404.
+ */
+export interface ChatMemory extends LongTermMemory {
+    list(ownerId: string): Promise<{
+        notes: MemoryNote[];
+        counts: MemoryCounts;
+    }>;
+    create(ownerId: string, input: unknown): Promise<MemoryResult<MemoryNote>>;
+    update(ownerId: string, id: string, version: number, input: unknown): Promise<MemoryResult<MemoryNote>>;
+    remove(ownerId: string, id: string, version: number): Promise<MemoryResult<{
+        deleted: string;
+    }>>;
+    clear(ownerId: string): Promise<number>;
+    listMerges?(ownerId: string, limit?: number): Promise<MemoryMergeRecord[]>;
+    revertMerge?(ownerId: string, runId: string): Promise<MemoryMergeRevertResult>;
+}
+/**
+ * Всё под `{base}/memory`. `segments` — путь после `memory`. Человек уже определён; память по своей природе
+ * его собственная, поэтому чужая запись для сервера — просто «не найдена».
+ */
+export declare function handleMemoryRequest(input: {
+    memory: ChatMemory;
+    request: Request;
+    userId: string;
+    segments: string[];
+}): Promise<Response>;

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

@@ -0,0 +1,14 @@
+/** Данные нового чата из браузера: решает приложение (`ChatHandlerOptions.newChatData`). */
+export type NewChatDataResolver = (input: {
+    user: {
+        id: string;
+    };
+    request: Request;
+}) => Promise<Record<string, unknown> | undefined> | Record<string, unknown> | undefined;
+/** Ответ приложения: объект данных или `undefined`. Другое — ошибка приложения, а не человека: обработчик ответит 500. */
+export declare function resolveNewChatData(resolve: NewChatDataResolver, input: {
+    user: {
+        id: string;
+    };
+    request: Request;
+}): Promise<Record<string, unknown> | undefined>;

package/dist/types/next.d.ts

@@ -0,0 +1,8 @@
+import type { ChatHandler } from "./chat-handler.js";
+type RouteHandler = (request: Request) => Promise<Response>;
+declare const routeMethods: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"];
+/** Методы для файла маршрута Next.js (App Router): `export const { GET, POST, … } = createNextRouteHandlers(handler)`. */
+export type NextRouteHandlers = Record<(typeof routeMethods)[number], RouteHandler>;
+/** Отдаёт обработчик чата (или расширения с такой же формой: `basePath` и `fetch`) как обработчики маршрута Next.js; ответ идёт как есть, поток не буферизуется. */
+export declare function createNextRouteHandlers(handler: Pick<ChatHandler, "fetch">): NextRouteHandlers;
+export {};

package/dist/types/node.d.ts

@@ -0,0 +1,11 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { ChatHandler } from "./chat-handler.js";
+/** Слушатель для `http.createServer` и промежуточный обработчик Express: `app.use(toNodeListener(handler))`. */
+export type NodeListener = (req: IncomingMessage, res: ServerResponse, next?: (error?: unknown) => void) => void;
+/**
+ * Отдаёт обработчик чата (или расширения с такой же формой: `basePath` и `fetch`) как слушатель Node.
+ * Адрес вне `basePath` — `next()`, без `next` — 404. Тело запроса идёт потоком; уже прочитанное разборщиком (`req.body`)
+ * уходит как есть. Ответ пишется по кускам, без буфера. Разрыв соединения до конца ответа отменяет запрос
+ * (`request.signal`) и поток ответа.
+ */
+export declare function toNodeListener(handler: Pick<ChatHandler, "basePath" | "fetch">): NodeListener;

package/dist/types/request-body.d.ts

@@ -0,0 +1,11 @@
+/** Больше этого тело JSON не читается: самое длинное сообщение (100 000 знаков) с местом на экране занимает меньше 0,5 МиБ. */
+export declare const MAX_JSON_BODY_BYTES: number;
+/** Тело запроса длиннее предела: оно не дочитано и не разобрано, ответ — 413. */
+export declare class RequestBodyTooLargeError extends Error {
+    constructor(maxBytes: number);
+}
+/**
+ * JSON тела не длиннее `maxBytes`: заявленная длина больше — тело не читается, поток длиннее — чтение обрывается;
+ * тогда `RequestBodyTooLargeError`. Нет тела или не JSON — `null`.
+ */
+export declare function readJsonBody(request: Request, maxBytes?: number): Promise<unknown>;

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

@@ -0,0 +1,31 @@
+import type { ChatGreeting, ChatService, TurnRefusal } from "@ykurilov/agent-chat-core";
+/** Что приложение отдаёт для чата объекта: данные (только для сервера), название и приветствие нового чата. */
+export interface SubjectChatSettings {
+    /** JSON-объект до 16 КБ: инструментам и хукам на сервере, в браузер не уходит. Пишется только при создании чата. */
+    data?: Record<string, unknown>;
+    /** Название нового чата; нет — из первого сообщения человека. */
+    title?: string;
+    /** Первое сообщение от агента в новом чате. */
+    greeting?: ChatGreeting;
+}
+/**
+ * Решение приложения о чате объекта: настройки или отказ `{ code, message }` (человеку нельзя в этот объект). Отказ
+ * узнаётся по полю `code`.
+ */
+export type SubjectChatsResolver = (input: {
+    user: {
+        id: string;
+    };
+    key: string;
+    request: Request;
+}) => Promise<SubjectChatSettings | TurnRefusal>;
+/** Отказ приложения ответом 403 `turn_refused`: код и текст безопасно показать человеку. */
+export declare function turnRefusalResponse(refusal: TurnRefusal): Response;
+/** `POST {base}/subject { key }` → `{ id, created }`: найти или создать чат объекта человека. */
+export declare function openSubjectChatRoute(input: {
+    request: Request;
+    userId: string;
+    service: Pick<ChatService, "openSubjectChat">;
+    resolve: SubjectChatsResolver;
+    invalid: () => Response;
+}): Promise<Response>;

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

@@ -0,0 +1,29 @@
+import type { AgentChannel, ChatEvent, ChatTurnTrigger, HiddenStateKey, TaskView } from "@ykurilov/agent-chat-core";
+/** Как часто поток сверяется с базой, пока у чата идут задачи. */
+export declare const WATCH_RECONCILE_EVERY_MS = 5000;
+/** Событие для вкладки: без владельца — он ей не нужен. */
+export type WatchEvent = ChatEvent extends infer Event ? (Event extends unknown ? Omit<Event, "ownerId"> : never) : never;
+export interface WatchStreamOptions {
+    ownerId: string;
+    chatId: string;
+    /** Запрос вкладки: клиент ушёл — поток закрывается, даже если его так и не начали читать. */
+    signal?: AbortSignal;
+    subscribeEvents(listener: (event: ChatEvent) => void): () => void;
+    /** Ключи состояния, которые не уходят вкладке в `state-changed`; нет — только служебные ключи SDK. */
+    hiddenStateKey?: HiddenStateKey;
+    /** Задачи чата; нет фона — сверки нет. */
+    listTasks?: () => Promise<TaskView[]>;
+    /** Ход, ответ которого идёт в базе, но не на этой копии сервера, с источником и каналом по истории; нет — `null`. */
+    detachedTurn(): Promise<{
+        messageId: string;
+        trigger: ChatTurnTrigger;
+        channel: AgentChannel;
+    } | null>;
+    onClose(): void;
+    logError(message: string): void;
+}
+/**
+ * События одного чата: ход начался, ход закончился, задачи изменились. Пока у чата идут задачи, раз в 5 с поток
+ * сверяется с базой: так видны ход и задачи, которые ведёт другая копия сервера.
+ */
+export declare function createWatchStream(options: WatchStreamOptions): ReadableStream<WatchEvent>;

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@ykurilov/agent-chat-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.56.0",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": {
+      "@ykurilov/agent-chat-source": "./src/index.ts",
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./hono": {
+      "@ykurilov/agent-chat-source": "./src/hono.ts",
+      "types": "./dist/types/hono.d.ts",
+      "import": "./dist/hono.js"
+    },
+    "./next": {
+      "@ykurilov/agent-chat-source": "./src/next.ts",
+      "types": "./dist/types/next.d.ts",
+      "import": "./dist/next.js"
+    },
+    "./node": {
+      "@ykurilov/agent-chat-source": "./src/node.ts",
+      "types": "./dist/types/node.d.ts",
+      "import": "./dist/node.js"
+    }
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ykurilov/agent-chat-sdk.git",
+    "directory": "packages/server"
+  },
+  "dependencies": {
+    "ai": "7.0.122",
+    "@ykurilov/agent-chat-core": "0.56.0"
+  },
+  "peerDependencies": {
+    "hono": "^4.13.10"
+  },
+  "peerDependenciesMeta": {
+    "hono": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@ai-sdk/provider": "4.0.19",
+    "hono": "^4.13.10"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-package.mjs",
+    "typecheck": "tsc -p tsconfig.json"
+  }
 }