@nextclaw/ui 0.12.10 → 0.12.11

package/src/features/system-status/utils/system-status.utils.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it } from 'vitest';
+import { t } from '@/lib/i18n';
+import {
+  resolveChatRuntimeMessage,
+  resolveSystemConnectionStatus,
+  toSystemStatusView,
+} from './system-status.utils';
+
+describe('resolveSystemConnectionStatus', () => {
+  it('maps cold-starting to connecting', () => {
+    expect(resolveSystemConnectionStatus('cold-starting')).toBe('connecting');
+  });
+
+  it('maps ready to connected', () => {
+    expect(resolveSystemConnectionStatus('ready')).toBe('connected');
+  });
+
+  it('maps stalled to disconnected', () => {
+    expect(resolveSystemConnectionStatus('stalled')).toBe('disconnected');
+  });
+
+  it('maps service-transitioning to connecting', () => {
+    expect(resolveSystemConnectionStatus('service-transitioning')).toBe(
+      'connecting'
+    );
+  });
+});
+
+describe('resolveChatRuntimeMessage', () => {
+  it('uses the startup message during cold start', () => {
+    expect(
+      resolveChatRuntimeMessage({
+        lifecyclePhase: 'cold-starting',
+        hasReachedReady: false,
+        lastReadyAt: null,
+        recoveryStartedAt: null,
+        bootstrapStatus: null,
+        lastError: null,
+        lastTransportError: null,
+        runtimeControlView: null,
+        runtimeControlError: null,
+        activeSystemAction: null,
+        lastSystemActionError: null,
+      })
+    ).toBe(t('chatRuntimeInitializing'));
+  });
+
+  it('uses the bootstrap error when startup failed', () => {
+    expect(
+      resolveChatRuntimeMessage({
+        lifecyclePhase: 'startup-failed',
+        hasReachedReady: false,
+        lastReadyAt: null,
+        recoveryStartedAt: null,
+        bootstrapStatus: {
+          phase: 'error',
+          ncpAgent: {
+            state: 'error',
+            error: 'boom',
+          },
+          pluginHydration: {
+            state: 'pending',
+            loadedPluginCount: 0,
+            totalPluginCount: 0,
+          },
+          channels: {
+            state: 'pending',
+            enabled: [],
+          },
+          remote: {
+            state: 'pending',
+          },
+          lastError: 'boom',
+        },
+        lastError: null,
+        lastTransportError: null,
+        runtimeControlView: null,
+        runtimeControlError: null,
+        activeSystemAction: null,
+        lastSystemActionError: null,
+      })
+    ).toBe('boom');
+  });
+
+  it('prefers the centralized action message while a system action is running', () => {
+    expect(
+      resolveChatRuntimeMessage({
+        lifecyclePhase: 'ready',
+        hasReachedReady: true,
+        lastReadyAt: Date.now(),
+        recoveryStartedAt: null,
+        bootstrapStatus: null,
+        lastError: null,
+        lastTransportError: null,
+        runtimeControlView: null,
+        runtimeControlError: null,
+        activeSystemAction: {
+          action: 'restart-service',
+          lifecycle: 'recovering',
+          serviceState: null,
+          message: 'NextClaw 正在恢复连接',
+        },
+        lastSystemActionError: null,
+      })
+    ).toBe('NextClaw 正在恢复连接');
+  });
+});
+
+describe('toSystemStatusView', () => {
+  it('keeps stalled chat blocked without surfacing a timeout banner', () => {
+    expect(
+      toSystemStatusView({
+        lifecyclePhase: 'stalled',
+        hasReachedReady: true,
+        lastReadyAt: Date.now(),
+        recoveryStartedAt: Date.now(),
+        bootstrapStatus: null,
+        lastError: 'Failed to fetch',
+        lastTransportError: 'Failed to fetch',
+        runtimeControlView: null,
+        runtimeControlError: null,
+        activeSystemAction: null,
+        lastSystemActionError: null,
+      })
+    ).toMatchObject({
+      isChatBlocked: true,
+      chatMessage: null,
+      connectionStatus: 'disconnected',
+      phase: 'stalled',
+    });
+  });
+});

package/src/features/system-status/utils/system-status.utils.ts

@@ -0,0 +1,202 @@
+import { t } from '@/lib/i18n';
+import type {
+  RuntimeControlAction,
+  RuntimeLifecycleState,
+  RuntimeServiceState,
+} from '@/api/runtime-control.types';
+import type {
+  RuntimeControlPanelView,
+  RuntimeStatusBadgeView,
+  SystemConnectionStatus,
+  SystemStatusPhase,
+  SystemStatusState,
+  SystemStatusView,
+} from '@/features/system-status/types/system-status.types';
+
+function resolveSystemStatusPhase(state: SystemStatusState): SystemStatusPhase {
+  return state.activeSystemAction ? 'service-transitioning' : state.lifecyclePhase;
+}
+
+export function resolveSystemConnectionStatus(
+  phase: SystemStatusPhase
+): SystemConnectionStatus {
+  if (phase === 'ready') {
+    return 'connected';
+  }
+  if (phase === 'startup-failed' || phase === 'stalled') {
+    return 'disconnected';
+  }
+  return 'connecting';
+}
+
+export function resolveChatRuntimeMessage(
+  state: SystemStatusState
+): string | null {
+  if (state.activeSystemAction?.message?.trim()) {
+    return state.activeSystemAction.message.trim();
+  }
+  if (state.lifecyclePhase === 'cold-starting') {
+    return t('chatRuntimeInitializing');
+  }
+  if (state.lifecyclePhase === 'startup-failed') {
+    return (
+      state.bootstrapStatus?.ncpAgent.error?.trim() ||
+      state.bootstrapStatus?.lastError?.trim() ||
+      state.lastError?.trim() ||
+      t('chatRuntimeInitializationFailed')
+    );
+  }
+  return null;
+}
+
+export function toSystemStatusView(
+  state: SystemStatusState
+): SystemStatusView {
+  const phase = resolveSystemStatusPhase(state);
+  return {
+    ...state,
+    phase,
+    connectionStatus: resolveSystemConnectionStatus(phase),
+    isChatBlocked: phase !== 'ready',
+    chatMessage: resolveChatRuntimeMessage(state),
+  };
+}
+
+function resolveActionLifecycleLabel(
+  action: RuntimeControlAction
+): RuntimeLifecycleState {
+  if (action === 'start-service') {
+    return 'starting-service';
+  }
+  if (action === 'stop-service') {
+    return 'stopping-service';
+  }
+  if (action === 'restart-service') {
+    return 'restarting-service';
+  }
+  return 'restarting-app';
+}
+
+function resolveActionServiceState(
+  action: RuntimeControlAction
+): RuntimeServiceState | null {
+  if (action === 'start-service') {
+    return 'starting';
+  }
+  if (action === 'stop-service') {
+    return 'stopping';
+  }
+  if (action === 'restart-service') {
+    return 'restarting';
+  }
+  return null;
+}
+
+export function buildActiveSystemActionState(params: {
+  action: RuntimeControlAction;
+  message: string | null;
+}): SystemStatusState['activeSystemAction'] {
+  const { action, message } = params;
+  return {
+    action,
+    lifecycle: resolveActionLifecycleLabel(action),
+    serviceState: resolveActionServiceState(action),
+    message,
+  };
+}
+
+export function toRuntimeStatusBadgeView(
+  state: SystemStatusState
+): RuntimeStatusBadgeView {
+  if (state.runtimeControlError) {
+    return {
+      tone: 'inactive',
+      title: t('runtimeControlLoadFailed'),
+      description: state.runtimeControlError,
+      reasonLines: [],
+      actionLabel: null,
+      isBusy: false,
+    };
+  }
+
+  if (!state.runtimeControlView) {
+    return {
+      tone: 'inactive',
+      title: t('runtimeStatusLoadingTitle'),
+      description: t('runtimeStatusLoadingDescription'),
+      reasonLines: [],
+      actionLabel: null,
+      isBusy: Boolean(state.activeSystemAction),
+    };
+  }
+
+  if (state.activeSystemAction) {
+    return {
+      tone: 'attention',
+      title: t('runtimeControlTitle'),
+      description:
+        state.activeSystemAction.message ||
+        state.runtimeControlView.message ||
+        t('runtimeControlDescription'),
+      reasonLines: [],
+      actionLabel: null,
+      isBusy: true,
+    };
+  }
+
+  const view = state.runtimeControlView;
+  if (view.pendingRestart) {
+    return {
+      tone: 'attention',
+      title: t('runtimeStatusPendingRestartTitle'),
+      description: t('runtimeStatusPendingRestartDescription'),
+      reasonLines:
+        view.pendingRestart.changedPaths.length > 0
+          ? view.pendingRestart.changedPaths.map((path: string) =>
+              t('runtimeStatusPendingRestartReasonItem').replace('{path}', path)
+            )
+          : [view.pendingRestart.message],
+      actionLabel: view.canRestartService.available
+        ? t('runtimeStatusRestartAction')
+        : null,
+      isBusy: false,
+    };
+  }
+
+  return {
+    tone: view.lifecycle === 'healthy' ? 'healthy' : 'inactive',
+    title: t('runtimeStatusHealthyTitle'),
+    description: t('runtimeStatusHealthyDescription'),
+    reasonLines: [],
+    actionLabel: null,
+    isBusy: false,
+  };
+}
+
+export function toRuntimeControlPanelView(
+  state: SystemStatusState
+): RuntimeControlPanelView {
+  const action = state.activeSystemAction;
+  const controlView = state.runtimeControlView;
+  const visibleLifecycle =
+    action?.lifecycle ?? controlView?.lifecycle ?? 'healthy';
+  const visibleServiceState =
+    action?.serviceState ?? controlView?.serviceState ?? 'unknown';
+  const visibleMessage =
+    action?.message ||
+    state.lastSystemActionError ||
+    controlView?.message ||
+    t('runtimeControlDescription');
+
+  return {
+    controlView,
+    visibleLifecycle,
+    visibleServiceState,
+    visibleMessage,
+    busyAction: action?.action ?? null,
+    busy: Boolean(action),
+    pendingRestart: controlView?.pendingRestart ?? null,
+    errorMessage:
+      state.lastSystemActionError || state.runtimeControlError || null,
+  };
+}

package/src/hooks/use-realtime-query-bridge.ts

@@ -1,12 +1,9 @@
 import { useEffect, useRef } from 'react';
 import { applyNcpSessionRealtimeEvent } from '@/api/ncp-session-query-cache';
+import { systemStatusManager } from '@/features/system-status';
 import { appClient } from '@/transport';
-import { useUiStore } from '@/stores/ui.store';
 import type { QueryClient } from '@tanstack/react-query';
 
-type ConnectionStatus = 'connected' | 'disconnected' | 'connecting';
-type SetConnectionStatus = (status: ConnectionStatus) => void;
-
 function shouldInvalidateConfigQuery(configPath: string) {
   const normalized = configPath.trim().toLowerCase();
   if (!normalized) {
@@ -39,22 +36,34 @@ function handleConfigUpdatedEvent(queryClient: QueryClient | undefined, path: st
 }
 
 function handleRealtimeEvent(
-  queryClient: QueryClient | undefined,
-  setConnectionStatus: SetConnectionStatus,
-  shouldResyncSessionsRef: { current: boolean },
-  event: Parameters<Parameters<typeof appClient.subscribe>[0]>[0]
+  params: {
+    queryClient: QueryClient | undefined;
+    shouldResyncSessions: boolean;
+    clearShouldResyncSessions: () => void;
+    markShouldResyncSessions: () => void;
+    event: Parameters<Parameters<typeof appClient.subscribe>[0]>[0];
+  }
 ): void {
+  const {
+    queryClient,
+    shouldResyncSessions,
+    clearShouldResyncSessions,
+    markShouldResyncSessions,
+    event,
+  } = params;
   if (event.type === 'connection.open') {
-    setConnectionStatus('connected');
-    if (shouldResyncSessionsRef.current) {
-      shouldResyncSessionsRef.current = false;
+    systemStatusManager.handleConnectionRestored();
+    if (shouldResyncSessions) {
+      clearShouldResyncSessions();
       queryClient?.invalidateQueries({ queryKey: ['ncp-sessions'] });
     }
     return;
   }
   if (event.type === 'connection.close' || event.type === 'connection.error') {
-    setConnectionStatus('disconnected');
-    shouldResyncSessionsRef.current = true;
+    systemStatusManager.handleConnectionInterrupted(
+      event.type === 'connection.error' ? event.payload?.message : null
+    );
+    markShouldResyncSessions();
     return;
   }
   if (event.type === 'config.updated') {
@@ -76,14 +85,21 @@ function handleRealtimeEvent(
 }
 
 export function useRealtimeQueryBridge(queryClient?: QueryClient) {
-  const { setConnectionStatus } = useUiStore();
   const shouldResyncSessionsRef = useRef(false);
 
   useEffect(() => {
-    setConnectionStatus('connecting');
-
     return appClient.subscribe((event) =>
-      handleRealtimeEvent(queryClient, setConnectionStatus, shouldResyncSessionsRef, event)
+      handleRealtimeEvent({
+        queryClient,
+        shouldResyncSessions: shouldResyncSessionsRef.current,
+        clearShouldResyncSessions: () => {
+          shouldResyncSessionsRef.current = false;
+        },
+        markShouldResyncSessions: () => {
+          shouldResyncSessionsRef.current = true;
+        },
+        event,
+      })
     );
-  }, [queryClient, setConnectionStatus]);
+  }, [queryClient]);
 }

package/src/lib/i18n.chat.ts

@@ -59,6 +59,14 @@ export const CHAT_LABELS: Record<string, { zh: string; en: string }> = {
   chatWorkspacePreviewTruncated: { zh: '内容已截断', en: 'Preview truncated' },
   chatSessionUnread: { zh: '会话有未读更新', en: 'Session has unread updates' },
   chatTyping: { zh: 'Agent 正在思考...', en: 'Agent is thinking...' },
+  chatRuntimeInitializing: {
+    zh: '聊天能力正在初始化。你可以先输入内容，完成后即可发送。',
+    en: 'Chat is still initializing. You can keep typing and send once startup finishes.'
+  },
+  chatRuntimeInitializationFailed: {
+    zh: '聊天能力启动失败，请稍后重试或检查服务日志。',
+    en: 'Chat startup failed. Please retry in a moment or inspect the service logs.'
+  },
   chatInputPlaceholder: { zh: '输入消息，输入 / 选择技能，Enter 发送，Shift + Enter 换行', en: 'Type a message, type / to select skills, Enter to send, Shift + Enter for newline' },
   chatInputHint: { zh: '支持多轮上下文，默认走当前会话。', en: 'Multi-turn context is preserved in the current session.' },
   chatSlashSectionCommands: { zh: '命令', en: 'Commands' },

package/src/platforms/desktop/index.ts

@@ -0,0 +1,20 @@
+export {
+  desktopPresenceManager,
+  DesktopPresenceManager,
+} from './managers/desktop-presence.manager';
+export {
+  desktopUpdateManager,
+  DesktopUpdateManager,
+} from './managers/desktop-update.manager';
+export { useDesktopPresenceStore } from './stores/desktop-presence.store';
+export { useDesktopUpdateStore } from './stores/desktop-update.store';
+export type {
+  DesktopPresencePreferences,
+  DesktopPresenceSnapshot,
+  DesktopReleaseChannel,
+  DesktopRuntimeControlResult,
+  DesktopUpdatePreferences,
+  DesktopUpdateSnapshot,
+  DesktopUpdateStatus,
+  NextClawDesktopBridge,
+} from './types/desktop-update.types';

package/src/{desktop → platforms/desktop}/managers/desktop-presence.manager.ts

@@ -1,8 +1,8 @@
 import type {
   DesktopPresencePreferences,
   NextClawDesktopBridge
-} from '@/desktop/desktop-update.types';
-import { useDesktopPresenceStore } from '@/desktop/stores/desktop-presence.store';
+} from '@/platforms/desktop/types/desktop-update.types';
+import { useDesktopPresenceStore } from '@/platforms/desktop/stores/desktop-presence.store';
 import { t } from '@/lib/i18n';
 import { toast } from 'sonner';
 

package/src/{desktop → platforms/desktop}/managers/desktop-update.manager.ts

@@ -3,8 +3,8 @@ import type {
   DesktopUpdatePreferences,
   DesktopUpdateSnapshot,
   NextClawDesktopBridge
-} from '@/desktop/desktop-update.types';
-import { useDesktopUpdateStore } from '@/desktop/stores/desktop-update.store';
+} from '@/platforms/desktop/types/desktop-update.types';
+import { useDesktopUpdateStore } from '@/platforms/desktop/stores/desktop-update.store';
 import { t } from '@/lib/i18n';
 import { toast } from 'sonner';
 

package/src/{desktop → platforms/desktop}/stores/desktop-presence.store.ts

@@ -1,4 +1,4 @@
-import type { DesktopPresenceSnapshot } from '@/desktop/desktop-update.types';
+import type { DesktopPresenceSnapshot } from '@/platforms/desktop/types/desktop-update.types';
 import { create } from 'zustand';
 
 type DesktopPresenceBusyAction = 'loading' | 'saving-preferences' | null;

package/src/{desktop → platforms/desktop}/stores/desktop-update.store.ts

@@ -1,4 +1,4 @@
-import type { DesktopUpdateSnapshot } from '@/desktop/desktop-update.types';
+import type { DesktopUpdateSnapshot } from '@/platforms/desktop/types/desktop-update.types';
 import { create } from 'zustand';
 
 type DesktopUpdateBusyAction =

package/src/stores/ui.store.ts

@@ -1,12 +1,6 @@
 import { create } from 'zustand';
 
-type ConnectionStatus = 'connected' | 'disconnected' | 'connecting';
-
 interface UiState {
-  // Connection status
-  connectionStatus: ConnectionStatus;
-  setConnectionStatus: (status: ConnectionStatus) => void;
-
   // Channel modal
   channelModal: { open: boolean; channel?: string };
   openChannelModal: (channel?: string) => void;
@@ -14,9 +8,6 @@ interface UiState {
 }
 
 export const useUiStore = create<UiState>((set) => ({
-  connectionStatus: 'disconnected',
-  setConnectionStatus: (status) => set({ connectionStatus: status }),
-
   channelModal: { open: false },
   openChannelModal: (channel) => set({ channelModal: { open: true, channel } }),
   closeChannelModal: () => set({ channelModal: { open: false } })

package/src/transport/{app-client.ts → app-client.service.ts}

@@ -1,5 +1,5 @@
 import { API_BASE } from '@/api/api-base';
-import { LocalAppTransport } from './local.transport';
+import { LocalAppTransport } from './local-transport.service';
 import { RemoteSessionMultiplexTransport } from './remote.transport';
 import type { AppTransport, RemoteRuntimeInfo, RequestInput, StreamInput, StreamSession } from './transport.types';
 
@@ -59,18 +59,18 @@ class AppClient {
 
   constructor(private readonly apiBase: string = API_BASE) {}
 
-  private async getTransport(): Promise<AppTransport> {
+  private getTransport = async (): Promise<AppTransport> => {
     if (!this.transportPromise) {
       this.transportPromise = resolveRuntime(this.apiBase);
     }
     return await this.transportPromise;
-  }
+  };
 
-  async request<T>(input: RequestInput): Promise<T> {
+  request = async <T>(input: RequestInput): Promise<T> => {
     return await (await this.getTransport()).request<T>(input);
-  }
+  };
 
-  openStream<TFinal = unknown>(input: StreamInput): StreamSession<TFinal> {
+  openStream = <TFinal = unknown>(input: StreamInput): StreamSession<TFinal> => {
     let currentSession: StreamSession<TFinal> | null = null;
     let resolveFinished!: (value: TFinal) => void;
     let rejectFinished!: (error: Error) => void;
@@ -94,9 +94,9 @@ class AppClient {
       finished,
       cancel: () => currentSession?.cancel()
     };
-  }
+  };
 
-  subscribe(handler: (event: Parameters<Parameters<AppTransport['subscribe']>[0]>[0]) => void): () => void {
+  subscribe = (handler: (event: Parameters<Parameters<AppTransport['subscribe']>[0]>[0]) => void): () => void => {
     let unsubscribe = () => {};
     let active = true;
     void this.getTransport().then((transport) => {
@@ -117,7 +117,7 @@ class AppClient {
       active = false;
       unsubscribe();
     };
-  }
+  };
 }
 
 export const appClient = new AppClient();

package/src/transport/app-client.test.ts

@@ -21,12 +21,16 @@ describe('appClient runtime detection', () => {
     );
     vi.stubGlobal('fetch', fetchMock);
 
-    const { LocalAppTransport } = await import('@/transport/local.transport');
-    const localRequest = vi
-      .spyOn(LocalAppTransport.prototype, 'request')
-      .mockResolvedValue({ ok: true } as never);
+    const localRequest = vi.fn().mockResolvedValue({ ok: true } as never);
+    vi.doMock('@/transport/local-transport.service', () => ({
+      LocalAppTransport: class {
+        request = localRequest;
+        openStream = vi.fn();
+        subscribe = vi.fn();
+      }
+    }));
 
-    const { appClient } = await import('@/transport/app-client');
+    const { appClient } = await import('@/transport/app-client.service');
     const result = await appClient.request<{ ok: boolean }>({
       method: 'GET',
       path: '/api/config'

package/src/transport/index.ts

@@ -1,4 +1,4 @@
-export { appClient } from './app-client';
+export { appClient } from './app-client.service';
 export type {
   AppEvent,
   AppTransport,

package/src/transport/{local.transport.ts → local-transport.service.ts}

@@ -1,6 +1,7 @@
 import { API_BASE } from '@/api/api-base';
-import { requestRawApiResponse } from '@/api/raw-client';
+import { requestRawApiResponse } from '@/api/raw-client.utils';
 import type { ApiResponse } from '@/api/types';
+import { systemStatusManager } from '@/features/system-status';
 import type { AppEvent, AppTransport, RequestInput, StreamInput, StreamSession } from './transport.types';
 import { readSseStreamResult } from './sse-stream';
 import { resolveTransportWebSocketUrl } from './transport-websocket-url';
@@ -42,7 +43,7 @@ class LocalRealtimeGateway {
 
   constructor(private readonly wsUrl: string) {}
 
-  subscribe(handler: EventHandler): () => void {
+  subscribe = (handler: EventHandler): () => void => {
     this.subscribers.add(handler);
     if (this.subscribers.size === 1) {
       this.connect();
@@ -56,15 +57,15 @@ class LocalRealtimeGateway {
         this.disconnect();
       }
     };
-  }
+  };
 
-  private emit(event: AppEvent): void {
+  private emit = (event: AppEvent): void => {
     for (const subscriber of this.subscribers) {
       subscriber(event);
     }
-  }
+  };
 
-  private connect(): void {
+  private connect = (): void => {
     if (this.socket && (this.socket.readyState === WebSocket.CONNECTING || this.socket.readyState === WebSocket.OPEN)) {
       return;
     }
@@ -96,9 +97,9 @@ class LocalRealtimeGateway {
         this.scheduleReconnect();
       }
     };
-  }
+  };
 
-  private scheduleReconnect(): void {
+  private scheduleReconnect = (): void => {
     if (this.reconnectTimer !== null) {
       return;
     }
@@ -106,9 +107,9 @@ class LocalRealtimeGateway {
       this.reconnectTimer = null;
       this.connect();
     }, 3_000);
-  }
+  };
 
-  private disconnect(): void {
+  private disconnect = (): void => {
     this.manualClose = true;
     if (this.reconnectTimer !== null) {
       window.clearTimeout(this.reconnectTimer);
@@ -116,7 +117,7 @@ class LocalRealtimeGateway {
     }
     this.socket?.close();
     this.socket = null;
-  }
+  };
 }
 
 export class LocalAppTransport implements AppTransport {
@@ -154,7 +155,7 @@ export class LocalAppTransport implements AppTransport {
       return response.data;
     } catch (error) {
       if (controller?.signal.aborted) {
-        const reason = controller.signal.reason;
+        const { reason } = controller.signal;
         throw new Error(typeof reason === 'string' && reason.trim() ? reason : `Request timed out: ${input.method} ${input.path}`);
       }
       if (error instanceof Error) {
@@ -196,6 +197,7 @@ export class LocalAppTransport implements AppTransport {
           signal: controller.signal
         });
       } catch (error) {
+        systemStatusManager.reportTransportFailure(formatUnknownTransportError(error));
         throw createErrorWithCause(
           `Stream request failed for ${input.method} ${input.path} | ${formatUnknownTransportError(error)}`,
           error