@dipertq/dsh-openviking-status 0.2.2 → 0.3.1

package/lib/client.d.cts

@@ -35,12 +35,139 @@ interface CommitOptions {
     keep_recent_count?: number;
 }
 /**
- * Результат операции коммита сессии
+ * Результат операции коммита сессии.
+ *
+ * Коммит двухфазный: `task_id` — идентификатор фоновой задачи Phase 2
+ * (Memory Extraction). Пробрасывается из ответа демона как оптимизация —
+ * позволяет чипу мгновенно привязаться к задаче, не дожидаясь опроса списка.
  */
 interface CommitResult {
     ok: boolean;
     error?: string;
+    /** Идентификатор фоновой задачи извлечения (Phase 2), если демон его вернул. */
+    task_id?: string;
+    /** Разрешённый `resource_id` формы `dsh-session-<uuid>`. */
+    resource_id?: string;
+}
+/**
+ * Статус жизненного цикла фоновой задачи извлечения (Phase 2).
+ * Дробного прогресса *внутри* задачи демон не отдаёт — только эти состояния.
+ */
+type ExtractionTaskStatus = "pending" | "running" | "completed" | "failed";
+/**
+ * Одна фоновая задача Phase 2 (`task_type: session_commit`).
+ *
+ * Промежуточные `stage`/`operation`/`meta` демон держит пустыми (`null`/`{}`);
+ * `result`/`token_usage` заполняются только по завершении.
+ */
+interface ExtractionTask {
+    task_id: string;
+    status: ExtractionTaskStatus;
+    resource_id?: string;
+    created_at?: string;
+    updated_at?: string;
+    /** Итог завершённой задачи: сколько воспоминаний записано/отредактировано. */
+    memory_write?: number;
+    memory_edit?: number;
+    /** Расход токенов завершённой задачи. */
+    token_usage?: number;
+    /** Текст ошибки для `failed`. */
+    error?: string;
 }
+/**
+ * Разбивка задач сессии по статусам. Считается на клиенте из одного списка —
+ * `running` и `pending` учитываются раздельно (демон их не схлопывает).
+ */
+interface ExtractionBreakdown {
+    running: number;
+    pending: number;
+    completed: number;
+    failed: number;
+    total: number;
+    /** Первая *выполняющаяся* задача (для «Show log» живого извлечения). */
+    firstRunning: ExtractionTask | null;
+    /** Последняя *завершённая* задача (для строки last extraction). */
+    lastCompleted: ExtractionTask | null;
+    /** Последняя *провалившаяся* задача (для warning-глифа и текста ошибки). */
+    lastFailed: ExtractionTask | null;
+}
+/** Одно событие ленты `execution_events` задачи (для «Show log»). */
+interface ExecutionEvent {
+    seq?: number;
+    recorded_at?: string;
+    kind?: string;
+    status?: string;
+    stage?: string | null;
+    operation?: string | null;
+    error?: string | null;
+}
+/** Исход чтения списка задач сессии. */
+type TasksReadResult = {
+    status: "ok";
+    breakdown: ExtractionBreakdown;
+    tasks: ExtractionTask[];
+} | {
+    status: "unauthorized";
+} | {
+    status: "missing";
+} | {
+    status: "unreachable";
+    detail?: string;
+} | {
+    status: "error";
+    detail?: string;
+};
+/** Исход чтения одной задачи с лентой событий. */
+type TaskEventsResult = {
+    status: "ok";
+    task: ExtractionTask;
+    events: ExecutionEvent[];
+} | {
+    status: "unauthorized";
+} | {
+    status: "missing";
+} | {
+    status: "unreachable";
+    detail?: string;
+} | {
+    status: "error";
+    detail?: string;
+};
+/** Верхняя граница `limit` списка задач у демона. */
+declare const TASKS_LIMIT_CAP = 200;
+/**
+ * Нормализовать временную метку в ISO-строку.
+ *
+ * Демон OpenViking отдаёт `created_at` / `updated_at` как числом секунд
+ * (Unix timestamp), так и ISO-строками в `created_at_iso` / `updated_at_iso`.
+ */
+declare function normalizeTimestamp(ts: unknown, isoFallback?: unknown): string | undefined;
+/**
+ * Извлечь массив сырых задач из ответа демона OpenViking.
+ *
+ * OpenViking GET /api/v1/tasks возвращает `{ status: "ok", result: [ ... ] }`,
+ * где `result` — сам массив задач. Также поддерживаются варианты с `items`,
+ * `tasks`, вложенным `result.items` или плоским массивом в корне.
+ */
+declare function extractTaskList(data: unknown): unknown[];
+/**
+ * Привести сырую задачу демона к {@link ExtractionTask}.
+ *
+ * `result` завершённой задачи несёт `memories_extracted{memory_write,memory_edit}`
+ * и `token_usage`; форма может лежать как в корне, так и во вложенном `result`.
+ */
+declare function normalizeExtractionTask(raw: Record<string, unknown>): ExtractionTask | null;
+/**
+ * Свести список задач в разбивку по статусам.
+ *
+ * Список приходит отсортированным по убыванию времени, поэтому первая
+ * `completed`/`failed` — самая свежая. `running` и `pending` считаются
+ * раздельно: мигание чипа завязано строго на `running`, backlog — на
+ * `pending`/`failed`.
+ */
+declare function computeBreakdown(tasks: ExtractionTask[]): ExtractionBreakdown;
+/** Нормализовать одно сырое событие ленты `execution_events`. */
+declare function normalizeExecutionEvent(raw: Record<string, unknown>): ExecutionEvent;
 /**
  * Исход попытки прочитать сессию.
  *
@@ -151,7 +278,24 @@ declare class OpenVikingClient {
      * Инициация фиксации (коммита) накопленных токенов сессии в долговременную память
      */
     commitSession(sessionId: string, options?: CommitOptions): Promise<CommitResult>;
+    /**
+     * Список задач Phase 2 (Memory Extraction) текущей сессии со сводной
+     * разбивкой по статусам.
+     *
+     * Через прокси: один запрос `GET /tasks?session=<id>`, разбивка считается
+     * здесь. Напрямую: разрешаем `resource_id` через кандидатов и запрашиваем
+     * `GET /api/v1/tasks?resource_id=<id>&task_type=session_commit&limit=200`.
+     */
+    listTasks(sessionId: string): Promise<TasksReadResult>;
+    /**
+     * Лениво загрузить одну задачу с лентой `execution_events` для «Show log».
+     */
+    fetchTaskEvents(taskId: string): Promise<TaskEventsResult>;
 }
+/**
+ * Нормализовать массив сырых задач, отбросив нераспознанные записи.
+ */
+declare function normalizeTaskList(raw: unknown): ExtractionTask[];
 /**
  * Экземпляр клиента по умолчанию с автоматическим определением конфигурации
  */
@@ -269,6 +413,63 @@ declare function inferCategory(uri: string): string | undefined;
 declare function parseRecalledMemories(input: string | any[] | null | undefined): RecalledMemoriesResult;
 
 declare const COMMIT_THRESHOLD = 20000;
+/** Интервалы адаптивного поллинга: покой vs активная фаза извлечения. */
+declare const POLL_INTERVAL_IDLE_MS = 15000;
+declare const POLL_INTERVAL_ACTIVE_MS = 2500;
+/**
+ * Определяет, находится ли опрос в активной фазе (2.5с вместо 15с).
+ *
+ * Активная фаза включается как при выполнении (`running >= 1`), так и при
+ * наличии задач в очереди (`pending >= 1`), чтобы успеть поймать запуск
+ * до завершения быстрой задачи.
+ */
+declare function shouldPollActive(breakdown?: ExtractionBreakdown | null): boolean;
+/**
+ * Состояние точки статуса (StateDot).
+ *
+ * - `offline` — демон недоступен (красный).
+ * - `session-unreadable` — сессия за ключом, счётчики недоступны (жёлтый статичный).
+ * - `busy` — идёт извлечение памяти (`running >= 1`): акцентный пульс.
+ * - `extraction-failed` — последняя задача провалилась: жёлтый + warning-глиф.
+ * - `online-idle` — норма (зелёный).
+ *
+ * Мигание завязано *строго* на `running`: `pending`-only не пульсирует.
+ */
+type ChipDotState = "offline" | "session-unreadable" | "busy" | "extraction-failed" | "online-idle";
+/**
+ * Свести состояние демона, сессии и разбивку задач Phase 2 к состоянию точки.
+ *
+ * Приоритет: недоступность демона → нечитаемая сессия → активное извлечение →
+ * провал последней задачи → норма. Провал показываем только когда *хвост*
+ * непуст (есть свежий `failed`) и при этом ничего не выполняется.
+ */
+declare function getChipDotState({ isOnline, sessionUnreadable, breakdown, }: {
+    isOnline: boolean;
+    sessionUnreadable: boolean;
+    breakdown?: ExtractionBreakdown | null;
+}): ChipDotState;
+/**
+ * Warning-глиф (circle-alert) для состояния `extraction-failed`.
+ *
+ * Инлайновый SVG, а не иконка из примитивов DSH: набор экспортируемых имён у
+ * примитивов не гарантирован, а отсутствующий глиф молча стал бы невидимым —
+ * ровно тот отказ, который прячется под работающим кодом. `currentColor`
+ * наследует цвет предупреждения от родителя.
+ */
+declare function WarningGlyph({ size, testId, }: {
+    size?: number;
+    testId?: string;
+}): React.JSX.Element;
+/**
+ * Оптимистично добавить `running`-задачу в разбивку после коммита.
+ *
+ * Точка пульсирует мгновенно по `task_id` из ответа коммита; следующий опрос
+ * списка заменит эту заглушку реальной задачей. Если такой `task_id` уже есть в
+ * списке (гонка с опросом) — оставляем как есть.
+ */
+declare function seedRunningTask(prev: TasksReadResult | null, taskId: string, resourceId?: string): TasksReadResult;
+/** Цвет точки для состояния StateDot. */
+declare function getDotColorForState(state: ChipDotState): string;
 /**
  * Селектор поверх снимка диалога — стандартный проп слотов со скоупом сессии.
  * Штатные чипы статистики DSH читают узлы ровно так же.
@@ -288,6 +489,8 @@ interface OpenVikingStatusChipProps {
     initialHealth?: HealthStatus;
     initialSessionData?: SessionStatus;
     initialSessionRead?: SessionReadResult;
+    /** Стартовая разбивка задач Phase 2 — для рендера вне слота и тестов. */
+    initialTasksRead?: TasksReadResult;
     initialOpen?: boolean;
 }
 /**
@@ -342,11 +545,32 @@ interface OpenVikingStatusPopoverProps {
     endpoint?: string;
     isCommitting?: boolean;
     commitError?: string | null;
+    /** Разбивка задач Phase 2 (Memory Extraction) текущей сессии. */
+    breakdown?: ExtractionBreakdown | null;
+    /** Клиент для ленивой загрузки `execution_events` в «Show log». */
+    client?: OpenVikingClient;
     onCommitNow?: () => Promise<void> | void;
     onClose?: () => void;
     className?: string;
     style?: React.CSSProperties;
 }
+/**
+ * Длительность задачи между двумя таймстампами, человекочитаемо (`4.2s`, `1m 12s`).
+ */
+declare function formatDuration(startIso?: string, endIso?: string): string | undefined;
+/**
+ * Строка last extraction для завершённой задачи:
+ * `<write> written, <edit> edited · <duration> · <relative-time>`.
+ *
+ * Части опускаются, если данных нет: длительность требует обоих таймстампов,
+ * относительное время — `updated_at`.
+ */
+declare function formatExtractionSummary(task: ExtractionTask, now?: number): string;
+/**
+ * Строка backlog `N pending / M failed`, только когда хвост непуст.
+ * Возвращает `null`, когда всё завершено (строку рисовать не нужно).
+ */
+declare function formatBacklog(breakdown?: ExtractionBreakdown | null): string | null;
 /**
  * Расчет процента заполнения пула накопленных токенов (0% - 100%).
  */
@@ -392,13 +616,28 @@ declare function getCategoryBadgeStyle(_category?: string): React.CSSProperties;
 declare function handleEscapeKey(event: {
     key: string;
 }, onClose?: () => void): boolean;
+/**
+ * Блок Phase 2 (Memory Extraction) рядом с `Commit Now`.
+ *
+ * - `running` → indeterminate-бар + `Extracting…` (без фейкового процента).
+ * - `completed` → строка last extraction + ровная зелёная точка.
+ * - backlog `N pending / M failed` — только когда хвост непуст.
+ * - `failed` → warning-глиф + текст ошибки.
+ * - «Show log» лениво тянет `execution_events` и рендерит ленту переходов.
+ *
+ * Глобальную очередь демона (Requeued и т.п.) блок не показывает намеренно.
+ */
+declare function ExtractionSection({ breakdown, client, }: {
+    breakdown?: ExtractionBreakdown | null;
+    client?: OpenVikingClient;
+}): React.JSX.Element | null;
 /**
  * Панель детального состояния контекстной памяти OpenViking (Status Popover).
  *
  * Оформление повторяет диалог статистики сессии DSH: та же поверхность, тень,
  * радиус, отступы и кегль.
  */
-declare function OpenVikingStatusPopover({ sessionId, health, sessionData, sessionRead, recalledResult, endpoint, isCommitting, commitError, onCommitNow, onClose, className, style, }: OpenVikingStatusPopoverProps): React.JSX.Element;
+declare function OpenVikingStatusPopover({ sessionId, health, sessionData, sessionRead, recalledResult, endpoint, isCommitting, commitError, breakdown, client, onCommitNow, onClose, className, style, }: OpenVikingStatusPopoverProps): React.JSX.Element;
 
 interface OpenVikingConfigData {
     endpoint: string;
@@ -429,4 +668,4 @@ declare const inject: string[];
  */
 declare function apply(ctx: any): void;
 
-export { COMMIT_THRESHOLD, type CommitOptions, type CommitResult, DEFAULT_OPENVIKING_ENDPOINT, type HealthStatus, OpenVikingClient, type OpenVikingConfigData, type OpenVikingHealth, type OpenVikingSessionData, OpenVikingSettingsSection, type OpenVikingSettingsSectionProps, OpenVikingStatusChip, type OpenVikingStatusChipProps, OpenVikingStatusPopover, type OpenVikingStatusPopoverProps, PROXY_OPENVIKING_ENDPOINT, 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 };
+export { COMMIT_THRESHOLD, type ChipDotState, type CommitOptions, type CommitResult, DEFAULT_OPENVIKING_ENDPOINT, type ExecutionEvent, type ExtractionBreakdown, ExtractionSection, type ExtractionTask, type ExtractionTaskStatus, type HealthStatus, OpenVikingClient, type OpenVikingConfigData, type OpenVikingHealth, type OpenVikingSessionData, OpenVikingSettingsSection, type OpenVikingSettingsSectionProps, OpenVikingStatusChip, type OpenVikingStatusChipProps, OpenVikingStatusPopover, type OpenVikingStatusPopoverProps, POLL_INTERVAL_ACTIVE_MS, POLL_INTERVAL_IDLE_MS, PROXY_OPENVIKING_ENDPOINT, type PeerId, type PendingTokens, type RecalledMemoriesResult, type RecalledMemoryItem, type SessionReadResult, type SessionStatus, TASKS_LIMIT_CAP, THEME, type TaskEventsResult, type TasksReadResult, type ThemeRole, type UseChat, WarningGlyph, apply, chatNodesToText, checkHealth, commitSession, computeBreakdown, defaultOpenVikingClient, extractTaskList, fetchSession, formatBacklog, formatDaemonVersion, formatDuration, formatEndpoint, formatExtractionSummary, formatMemoryLeafName, formatPendingTokens, formatRelativeTime, formatStatusLabel, formatTooltipTitle, getCategoryBadgeStyle, getChipDotState, getDotColorForState, getProgressBarColor, getProgressBarPercent, getSession, getStatusIndicatorColor, handleEscapeKey, inferCategory, inject, name, normalizeExecutionEvent, normalizeExtractionTask, normalizeTaskList, normalizeTimestamp, parseRecalledMemories, resolveApiKey, resolveEndpoint, seedRunningTask, shouldPollActive, themeVar, truncateSessionId };