@dipertq/dsh-openviking-status 0.1.7 → 0.1.8

package/lib/client.d.cts

@@ -40,6 +40,36 @@ interface CommitResult {
     ok: boolean;
     error?: string;
 }
+/**
+ * Исход попытки прочитать сессию.
+ *
+ * Причина неудачи важна: при `auth_mode: api_key` демон отвечает на `/health`
+ * и отказывает на сессии, и «нечитаемо» нельзя показывать как «накоплено ноль».
+ */
+type SessionReadResult = 
+/** Сессия прочитана. */
+{
+    status: "ok";
+    session: SessionStatus;
+}
+/** Демон требует ключ, которого у клиента нет. */
+ | {
+    status: "unauthorized";
+}
+/** Демон не знает такой сессии. */
+ | {
+    status: "missing";
+}
+/** До демона не удалось достучаться. */
+ | {
+    status: "unreachable";
+    detail?: string;
+}
+/** Демон ответил ошибкой или неожиданным телом. */
+ | {
+    status: "error";
+    detail?: string;
+};
 /**
  * Синонимы доменных понятий из CONTEXT.md
  */
@@ -79,8 +109,18 @@ declare class OpenVikingClient {
      */
     checkHealth(): Promise<HealthStatus>;
     /**
-     * Получение метаданных сессии по идентификатору с автоматическим разрешением префикса.
-     * При сетевых сбоях или ошибках авторизации возвращает null, не выбрасывая исключений.
+     * Чтение метаданных сессии с явной причиной неудачи.
+     *
+     * Демон может работать с `auth_mode: api_key`: тогда `/health` остаётся
+     * открытым, а сессия отвечает 401. Схлопывать это в «нет данных» нельзя —
+     * иначе интерфейс покажет живой индикатор рядом с нулями и умолчит о том,
+     * что счётчики просто недоступны.
+     */
+    readSession(sessionId: string): Promise<SessionReadResult>;
+    /**
+     * Получение метаданных сессии по идентификатору.
+     * Обёртка над {@link readSession} для вызывающих, которым причина неудачи
+     * не нужна: любая неудача сводится к null.
      */
     fetchSession(sessionId: string): Promise<SessionStatus | null>;
     /**
@@ -113,6 +153,62 @@ declare function getSession(sessionId: string, endpoint?: string, apiKey?: strin
  */
 declare function commitSession(sessionId: string, options?: CommitOptions, endpoint?: string, apiKey?: string): Promise<CommitResult>;
 
+/**
+ * Соответствие «визуальная роль → свойство темы DSH».
+ *
+ * Плагин стилизуется инлайново, поэтому каждое обращение к теме — строка
+ * `var(--dsw-…)`. CSS-переменные падают на fallback молча, и опечатка в имени
+ * выглядит как работающий код: именно так плагин однажды уехал на шестнадцать
+ * несуществующих свойств и перестал следовать теме вовсе, сохранив осмысленный
+ * вид.
+ *
+ * Единая таблица делает набор имён проверяемым как данные (`tests/theme.test.ts`
+ * сверяет их с тем, что объявляет `@deepseek-ai/dsh-client-ui-theme`), а заодно
+ * не даёт разойтись значениям между чипом и поповером.
+ *
+ * Значения подобраны по штатным компонентам DSH: чип повторяет `StatsPills`,
+ * панель — диалог статистики сессии из `@deepseek-ai/dsh-client-ui-chat`.
+ */
+declare const THEME: {
+    /** Фон всплывающей панели — тот же, что у меню и диалогов DSH. */
+    readonly panelSurface: "--dsw-specific-menu";
+    /** Тень панели. */
+    readonly panelElevation: "--dsw-elevation-prominent";
+    /** Контур панели; задаётся через переменную тени, а не через border. */
+    readonly panelStroke: "--dsw-alias-border-l1";
+    /** Заголовки и акцентный текст. */
+    readonly labelPrimary: "--dsw-alias-label-primary";
+    /** Основной текст панели. */
+    readonly labelSecondary: "--dsw-alias-label-secondary";
+    /** Приглушённый текст: подписи, значения, текст чипа в покое. */
+    readonly labelTertiary: "--dsw-alias-label-tertiary";
+    /** Разделительная линия внутри панели. */
+    readonly hairline: "--dsw-alias-border-l2";
+    /** Подсветка интерактивного элемента под курсором. */
+    readonly hoverBackground: "--dsw-alias-interactive-bg-hover";
+    /** Подсветка нажатого элемента. */
+    readonly activeBackground: "--dsw-alias-interactive-bg-active";
+    /** Демон доступен. */
+    readonly stateSuccess: "--dsw-alias-state-success-primary";
+    /** Демон недоступен или сессия нечитаема. */
+    readonly stateError: "--dsw-alias-state-error-primary";
+    /** Идёт коммит, либо накоплено близко к порогу. */
+    readonly stateWarning: "--dsw-alias-state-warn-primary";
+    /** Утопленная поверхность: дорожка прогресс-бара. */
+    readonly insetSurface: "--dsw-alias-bg-layer-2";
+    /** Моноширинный шрифт для идентификаторов и путей. */
+    readonly fontMono: "--dsw-font-markdown-code-font-family";
+};
+/** Роль в карте темы. */
+type ThemeRole = keyof typeof THEME;
+/**
+ * Ссылка на свойство темы для инлайнового стиля.
+ *
+ * Намеренно без fallback: подставленное значение скрыло бы отсутствующее
+ * свойство и вернуло бы ровно тот сбой, ради которого заведена эта карта.
+ */
+declare function themeVar(role: ThemeRole): string;
+
 interface RecalledMemoryItem {
     uri: string;
     category?: string;
@@ -149,15 +245,25 @@ declare function inferCategory(uri: string): string | undefined;
 declare function parseRecalledMemories(input: string | any[] | null | undefined): RecalledMemoriesResult;
 
 declare const COMMIT_THRESHOLD = 20000;
+/**
+ * Селектор поверх снимка диалога — стандартный проп слотов со скоупом сессии.
+ * Штатные чипы статистики DSH читают узлы ровно так же.
+ */
+type UseChat = (selector: (snapshot: any) => any) => any;
 interface OpenVikingStatusChipProps {
     sessionId: string;
-    messages?: any[];
+    /** Стандартный проп слота: доступ к снимку текущего диалога. */
+    useChat?: UseChat;
+    /** Узлы диалога напрямую — для вызова вне слота и для тестов. */
+    messages?: unknown;
+    /** Готовый текст диалога; приоритетнее остальных источников. */
     contextText?: string;
     client?: OpenVikingClient;
     onCommit?: () => void;
     className?: string;
     initialHealth?: HealthStatus;
     initialSessionData?: SessionStatus;
+    initialSessionRead?: SessionReadResult;
     initialOpen?: boolean;
 }
 /**
@@ -173,39 +279,41 @@ declare function formatStatusLabel(isOnline: boolean, recalledCount: number, pen
 /**
  * Формирование доступного заголовка / подсказки (title / aria-label).
  */
-declare function formatTooltipTitle({ isOnline, isCommitting, recalledCount, pendingTokens, }: {
+declare function formatTooltipTitle({ isOnline, isCommitting, recalledCount, pendingTokens, sessionUnreadable, }: {
     isOnline: boolean;
     isCommitting?: boolean;
     recalledCount: number;
     pendingTokens: number;
+    sessionUnreadable?: boolean;
 }): string;
 /**
- * Определение цвета индикатора состояния:
- * - Офлайн: красный
- * - Коммит: желтый / янтарный
- * - Онлайн: зеленый
+ * Состояние индикатора: офлайн, нечитаемая сессия, коммит или норма.
  */
-declare function getStatusIndicatorColor(isOnline: boolean, isCommitting?: boolean): string;
+declare function getStatusIndicatorColor(isOnline: boolean, isCommitting?: boolean, sessionUnreadable?: boolean): string;
 /**
- * Определение свечения индикатора:
- * Мягкое свечение только при статусе Online.
- */
-declare function getStatusGlow(isOnline: boolean, isCommitting?: boolean): string;
-/**
- * Извлечение сообщений сессии из глобального хранилища DSH (Redux store или window fallback).
+ * Извлечение текста из снимка диалога DSH.
+ *
+ * Узлы разнородны: текст лежит то в `content` строкой, то массивом блоков, то
+ * в `text`. Парсер воспоминаний работает по тексту, поэтому снимок сводится к
+ * одной строке, а неизвестные формы просто пропускаются.
  */
-declare function getFallbackSessionMessages(sessionId: string): any[] | undefined;
+declare function chatNodesToText(nodes: unknown): string;
 /**
- * Status Chip UI-компонент отображения состояния памяти OpenViking.
- * Формат в соответствии с CONTEXT.md:
- * 🟢 OV: <recalled> rec · <pending>k pend (или OV offline при недоступности сервиса).
+ * Status Chip: состояние памяти OpenViking в строке статистики под композером.
+ *
+ * Внешняя обёртка над {@link StatusChipView}: выбирает источник диалога.
+ * `useChat` — стандартный проп слота и сам по себе хук, поэтому вызывать его
+ * условно нельзя; развилка сделана выбором компонента, а не условием внутри
+ * одного.
  */
-declare function OpenVikingStatusChip({ sessionId, messages, contextText, client, onCommit, className, initialHealth, initialSessionData, initialOpen, }: OpenVikingStatusChipProps): React.JSX.Element;
+declare function OpenVikingStatusChip(props: OpenVikingStatusChipProps): React.JSX.Element;
 
 interface OpenVikingStatusPopoverProps {
     sessionId: string;
     health: HealthStatus | null;
     sessionData: SessionStatus | null;
+    /** Исход чтения сессии: отличает «нет доступа» от «накоплено ноль». */
+    sessionRead?: SessionReadResult | null;
     recalledResult?: RecalledMemoriesResult;
     endpoint?: string;
     isCommitting?: boolean;
@@ -220,24 +328,27 @@ interface OpenVikingStatusPopoverProps {
  */
 declare function getProgressBarPercent(pendingTokens: number, threshold?: number): number;
 /**
- * Цветовой сдвиг шкалы токенов:
- * - зеленый (< 80%)
- * - желтый / янтарный (>= 80%)
+ * Цветовой сдвиг шкалы токенов: предупреждение при приближении к порогу.
  */
 declare function getProgressBarColor(percent: number): string;
+/**
+ * Версия демона для показа в бейдже.
+ *
+ * OpenViking отдаёт `version` уже с префиксом (`v0.4.20`), а собственный `v`
+ * сверху давал `vv0.4.20`. Нормализуем, а не срезаем: префикс добавляется
+ * только если его нет, поэтому оба соглашения демона выглядят одинаково.
+ */
+declare function formatDaemonVersion(version?: string): string | undefined;
 /**
  * Форматирование относительного времени для метки последнего коммита (например, "2m ago").
  */
 declare function formatRelativeTime(isoOrTimestamp?: string | number | null, now?: number): string | undefined;
 /**
  * Извлечение имени конечного файла или относительного пути из viking:// URI.
- * Например:
- * viking://user/dsh/memories/preferences/user/code_style.md -> user/code_style.md
- * viking://user/dsh/memories/entities/project/wrench_board.md -> project/wrench_board.md
  */
 declare function formatMemoryLeafName(uri: string): string;
 /**
- * Форматирование адреса эндпоинта для отображения (удаляет протокол http:// / https://).
+ * Форматирование адреса эндпоинта для отображения (удаляет протокол).
  */
 declare function formatEndpoint(endpoint?: string): string;
 /**
@@ -245,9 +356,12 @@ declare function formatEndpoint(endpoint?: string): string;
  */
 declare function truncateSessionId(id: string, maxLen?: number): string;
 /**
- * Получение стилей бейджа категории воспоминания.
+ * Стиль бейджа категории.
+ *
+ * Эталонная панель DSH не кодирует категории цветом, а подходящих цветовых
+ * свойств тема не объявляет — поэтому все бейджи одинаковые и приглушённые.
  */
-declare function getCategoryBadgeStyle(category?: string): React.CSSProperties;
+declare function getCategoryBadgeStyle(_category?: string): React.CSSProperties;
 /**
  * Обработка нажатия клавиши Escape для закрытия панели.
  */
@@ -256,8 +370,11 @@ declare function handleEscapeKey(event: {
 }, onClose?: () => void): boolean;
 /**
  * Панель детального состояния контекстной памяти OpenViking (Status Popover).
+ *
+ * Оформление повторяет диалог статистики сессии DSH: та же поверхность, тень,
+ * радиус, отступы и кегль.
  */
-declare function OpenVikingStatusPopover({ sessionId, health, sessionData, recalledResult, endpoint, isCommitting, commitError, onCommitNow, onClose, className, style, }: OpenVikingStatusPopoverProps): React.JSX.Element;
+declare function OpenVikingStatusPopover({ sessionId, health, sessionData, sessionRead, recalledResult, endpoint, isCommitting, commitError, onCommitNow, onClose, className, style, }: OpenVikingStatusPopoverProps): React.JSX.Element;
 
 type OpenVikingSessionData = SessionStatus;
 type OpenVikingHealth = HealthStatus;
@@ -268,10 +385,15 @@ declare const inject: string[];
 /**
  * Точка входа клиентского плагина DSH.
  *
- * Занимает одну ячейку в `conversation.input.right` — списочном слоте строки
- * ввода со скоупом сессии. Скоуп означает, что `sessionId` приходит в компонент
- * как стандартный проп: доставать его из глобального стора не требуется.
+ * Занимает ячейку в `conversation.composer.dock` — списочном слоте строки
+ * статистики под композером, где уже живут чипы вроде «24 turns 645 steps».
+ * Там место пассивным показаниям; внутри композера чип читался как управляющий
+ * элемент.
+ *
+ * Слот со скоупом сессии, поэтому `sessionId` и `useChat` приходят стандартными
+ * пропами. Свой `id` обязателен: чужой занял бы и заменил ячейку соседа, а
+ * `order` выше нуля ставит чип после штатной статистики.
  */
 declare function apply(ctx: any): void;
 
-export { COMMIT_THRESHOLD, type CommitOptions, type CommitResult, DEFAULT_OPENVIKING_ENDPOINT, type HealthStatus, OpenVikingClient, type OpenVikingHealth, type OpenVikingSessionData, OpenVikingStatusChip, type OpenVikingStatusChipProps, OpenVikingStatusPopover, type OpenVikingStatusPopoverProps, type PeerId, type PendingTokens, type RecalledMemoriesResult, type RecalledMemoryItem, type SessionStatus, apply, checkHealth, commitSession, defaultOpenVikingClient, fetchSession, formatEndpoint, formatMemoryLeafName, formatPendingTokens, formatRelativeTime, formatStatusLabel, formatTooltipTitle, getCategoryBadgeStyle, getFallbackSessionMessages, getProgressBarColor, getProgressBarPercent, getSession, getStatusGlow, getStatusIndicatorColor, handleEscapeKey, inferCategory, inject, name, parseRecalledMemories, resolveApiKey, resolveEndpoint, truncateSessionId };
+export { COMMIT_THRESHOLD, type CommitOptions, type CommitResult, DEFAULT_OPENVIKING_ENDPOINT, type HealthStatus, OpenVikingClient, type OpenVikingHealth, type OpenVikingSessionData, OpenVikingStatusChip, type OpenVikingStatusChipProps, OpenVikingStatusPopover, type OpenVikingStatusPopoverProps, type PeerId, type PendingTokens, type RecalledMemoriesResult, type RecalledMemoryItem, type SessionReadResult, type SessionStatus, THEME, type ThemeRole, type UseChat, apply, chatNodesToText, checkHealth, commitSession, defaultOpenVikingClient, fetchSession, formatDaemonVersion, formatEndpoint, formatMemoryLeafName, formatPendingTokens, formatRelativeTime, formatStatusLabel, formatTooltipTitle, getCategoryBadgeStyle, getProgressBarColor, getProgressBarPercent, getSession, getStatusIndicatorColor, handleEscapeKey, inferCategory, inject, name, parseRecalledMemories, resolveApiKey, resolveEndpoint, themeVar, truncateSessionId };