@nextclaw/ui 0.12.18 → 0.12.20-beta.0

package/src/features/system-status/stores/runtime-update.store.ts

@@ -0,0 +1,24 @@
+import type { UpdateSnapshot } from '@nextclaw/kernel';
+import { create } from 'zustand';
+
+export type RuntimeUpdateBusyAction =
+  | 'checking'
+  | 'downloading'
+  | 'applying'
+  | 'saving-preferences'
+  | 'switching-channel'
+  | null;
+
+type RuntimeUpdateStoreState = {
+  supported: boolean;
+  initialized: boolean;
+  busyAction: RuntimeUpdateBusyAction;
+  snapshot: UpdateSnapshot | null;
+};
+
+export const useRuntimeUpdateStore = create<RuntimeUpdateStoreState>(() => ({
+  supported: false,
+  initialized: false,
+  busyAction: null,
+  snapshot: null
+}));

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

@@ -46,8 +46,6 @@ export type SystemStatusState = {
 export type SystemStatusView = SystemStatusState & {
   phase: SystemStatusPhase;
   connectionStatus: SystemConnectionStatus;
-  isChatBlocked: boolean;
-  chatMessage: string | null;
 };
 
 export type RuntimeStatusTone = 'healthy' | 'attention' | 'inactive';

package/src/features/system-status/utils/runtime-config-agent.utils.ts

@@ -4,7 +4,7 @@ import { t } from '@/shared/lib/i18n';
 export type DmScope = 'main' | 'per-peer' | 'per-channel-peer' | 'per-account-channel-peer';
 export type PeerKind = '' | 'direct' | 'group' | 'channel';
 export type RuntimeEntryDraft = RuntimeEntryView & { id: string; configText: string };
-export type RuntimeConfigEditorState = { agents: AgentProfileView[]; bindings: AgentBindingView[]; runtimeEntries: RuntimeEntryDraft[]; dmScope: DmScope; defaultContextTokens: number; defaultEngine: string };
+export type RuntimeConfigEditorState = { companionEnabled: boolean; agents: AgentProfileView[]; bindings: AgentBindingView[]; runtimeEntries: RuntimeEntryDraft[]; dmScope: DmScope; defaultContextTokens: number; defaultEngine: string };
 
 const DEFAULT_NARP_STDIO_ENTRY_CONFIG = {
   wireDialect: 'acp',
@@ -56,6 +56,7 @@ export function parseOptionalInt(value: string): number | undefined {
 
 export function createRuntimeConfigEditorState(config: ConfigView): RuntimeConfigEditorState {
   return {
+    companionEnabled: config.companion?.enabled === true,
     agents: (config.agents.list ?? []).map(hydrateRuntimeAgent),
     bindings: (config.bindings ?? []).map(hydrateRuntimeBinding),
     runtimeEntries: Object.entries(config.agents.runtimes?.entries ?? {}).map(([id, entry]) => ({ id, enabled: entry.enabled !== false, label: entry.label ?? '', type: entry.type, config: entry.config ?? {}, configText: JSON.stringify(entry.config ?? {}, null, 2) })),
@@ -81,6 +82,7 @@ export function toPersistedRuntimeAgent(agent: AgentProfileView): AgentProfileVi
 }
 
 export function createRuntimeConfigUpdatePayload(input: {
+  companionEnabled: boolean;
   agents: AgentProfileView[];
   bindings: AgentBindingView[];
   runtimeEntries: RuntimeEntryDraft[];
@@ -134,6 +136,9 @@ export function createRuntimeConfigUpdatePayload(input: {
     return entries;
   }, {});
   return {
+    companion: {
+      enabled: input.companionEnabled
+    },
     agents: {
       defaults: {
         contextTokens: Math.max(1000, input.defaultContextTokens),

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

@@ -1,7 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { t } from '@/shared/lib/i18n';
 import {
-  resolveChatRuntimeMessage,
   resolveSystemConnectionStatus,
   toSystemStatusView,
 } from './system-status.utils';
@@ -26,88 +24,8 @@ describe('resolveSystemConnectionStatus', () => {
   });
 });
 
-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', () => {
+  it('maps stalled to factual connection and lifecycle view fields', () => {
     expect(
       toSystemStatusView({
         lifecyclePhase: 'stalled',
@@ -123,8 +41,6 @@ describe('toSystemStatusView', () => {
         lastSystemActionError: null,
       })
     ).toMatchObject({
-      isChatBlocked: true,
-      chatMessage: null,
       connectionStatus: 'disconnected',
       phase: 'stalled',
     });

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

@@ -1,9 +1,9 @@
-import { t } from '@/shared/lib/i18n';
 import type {
   RuntimeControlAction,
   RuntimeLifecycleState,
   RuntimeServiceState,
 } from '@/shared/lib/api';
+import { t } from '@/shared/lib/i18n';
 import type {
   RuntimeControlPanelView,
   RuntimeStatusBadgeView,
@@ -29,26 +29,6 @@ export function resolveSystemConnectionStatus(
   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 {
@@ -57,8 +37,6 @@ export function toSystemStatusView(
     ...state,
     phase,
     connectionStatus: resolveSystemConnectionStatus(phase),
-    isChatBlocked: phase !== 'ready',
-    chatMessage: resolveChatRuntimeMessage(state),
   };
 }
 

package/src/platforms/desktop/managers/desktop-update.manager.ts

@@ -12,8 +12,10 @@ type DesktopUpdateBusyAction = 'checking' | 'downloading' | 'applying' | 'saving
 
 export class DesktopUpdateManager {
   private unsubscribe: (() => void) | null = null;
+  private subscriptionCount = 0;
 
   start = async () => {
+    this.subscriptionCount += 1;
     const desktopApi = this.getDesktopApi();
     if (!desktopApi) {
       useDesktopUpdateStore.setState({
@@ -56,6 +58,10 @@ export class DesktopUpdateManager {
   };
 
   stop = () => {
+    this.subscriptionCount = Math.max(0, this.subscriptionCount - 1);
+    if (this.subscriptionCount > 0) {
+      return;
+    }
     this.unsubscribe?.();
     this.unsubscribe = null;
   };

package/src/platforms/desktop/types/desktop-update.types.ts

@@ -1,29 +1,31 @@
-export type DesktopUpdateStatus =
-  | 'idle'
-  | 'checking'
-  | 'update-available'
-  | 'downloading'
-  | 'downloaded'
-  | 'up-to-date'
-  | 'failed';
+import type {
+  InstallationKind,
+  UpdateBlockReason,
+  UpdatePreferences,
+  UpdateProgress,
+  UpdateSnapshot,
+  UpdateStatus,
+} from '@nextclaw/kernel';
+
+export type DesktopUpdateStatus = Extract<
+  UpdateStatus,
+  'idle' | 'checking' | 'update-available' | 'downloading' | 'downloaded' | 'blocked' | 'up-to-date' | 'failed'
+>;
 
 export type DesktopReleaseChannel = 'stable' | 'beta';
 
-export type DesktopUpdatePreferences = {
-  automaticChecks: boolean;
-  autoDownload: boolean;
-};
+export type DesktopInstallationKind = InstallationKind;
+
+export type DesktopUpdateBlockReason = UpdateBlockReason;
+
+export type DesktopUpdateProgress = UpdateProgress;
+
+export type DesktopUpdatePreferences = UpdatePreferences;
 
-export type DesktopUpdateSnapshot = {
+export type DesktopUpdateSnapshot = UpdateSnapshot & {
   status: DesktopUpdateStatus;
   channel: DesktopReleaseChannel;
   launcherVersion: string;
-  currentVersion: string | null;
-  availableVersion: string | null;
-  downloadedVersion: string | null;
-  releaseNotesUrl: string | null;
-  lastCheckedAt: string | null;
-  errorMessage: string | null;
   preferences: DesktopUpdatePreferences;
 };
 

package/src/shared/components/common/brand-header.test.tsx

@@ -0,0 +1,142 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { MemoryRouter } from 'react-router-dom';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { useRuntimeUpdateStore } from '@/features/system-status';
+import { BrandHeader } from '@/shared/components/common/brand-header';
+import { setLanguage } from '@/shared/lib/i18n';
+
+const mocks = vi.hoisted(() => ({
+  applyDownloadedUpdate: vi.fn(),
+  downloadUpdate: vi.fn()
+}));
+
+vi.mock('@/features/system-status', async () => {
+  const actual = await vi.importActual<typeof import('@/features/system-status')>(
+    '@/features/system-status'
+  );
+  return {
+    ...actual,
+    runtimeUpdateManager: {
+      ...actual.runtimeUpdateManager,
+      applyDownloadedUpdate: mocks.applyDownloadedUpdate,
+      downloadUpdate: mocks.downloadUpdate
+    }
+  };
+});
+
+function renderBrandHeader() {
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: {
+        retry: false
+      }
+    }
+  });
+  queryClient.setQueryData(['app-meta'], {
+    name: 'NextClaw',
+    productVersion: '0.18.11'
+  });
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <MemoryRouter>
+        <BrandHeader suffix={null} />
+      </MemoryRouter>
+    </QueryClientProvider>
+  );
+}
+
+describe('BrandHeader', () => {
+  beforeEach(() => {
+    setLanguage('zh');
+    useRuntimeUpdateStore.setState({
+      supported: false,
+      initialized: false,
+      busyAction: null,
+      snapshot: null
+    });
+    mocks.applyDownloadedUpdate.mockReset();
+    mocks.downloadUpdate.mockReset();
+  });
+
+  it('shows update progress next to the product version', () => {
+    useRuntimeUpdateStore.setState({
+      supported: true,
+      initialized: true,
+      busyAction: null,
+      snapshot: {
+        status: 'downloading',
+        installationKind: 'desktop-bundle',
+        channel: 'stable',
+        hostVersion: '0.0.138',
+        currentVersion: '0.18.11',
+        availableVersion: '0.18.12',
+        downloadedVersion: null,
+        minimumHostVersion: null,
+        releaseNotesUrl: null,
+        lastCheckedAt: null,
+        progress: {
+          downloadedBytes: 50,
+          totalBytes: 100,
+          percent: 50
+        },
+        canAutoDownload: true,
+        canApplyInApp: false,
+        requiresRestart: false,
+        blockReason: null,
+        recoveryCommand: null,
+        errorMessage: null,
+        preferences: {
+          automaticChecks: true,
+          autoDownload: true
+        }
+      }
+    });
+
+    renderBrandHeader();
+
+    expect(screen.getByText('v0.18.11')).toBeTruthy();
+    expect(screen.getByText('下载 50%')).toBeTruthy();
+    expect(screen.queryByRole('button', { name: '更新' })).toBeNull();
+  });
+
+  it('applies the downloaded update from the version-adjacent update button', async () => {
+    const user = userEvent.setup();
+    useRuntimeUpdateStore.setState({
+      supported: true,
+      initialized: true,
+      busyAction: null,
+      snapshot: {
+        status: 'downloaded',
+        installationKind: 'desktop-bundle',
+        channel: 'stable',
+        hostVersion: '0.0.138',
+        currentVersion: '0.18.11',
+        availableVersion: null,
+        downloadedVersion: '0.18.12',
+        minimumHostVersion: null,
+        releaseNotesUrl: null,
+        lastCheckedAt: null,
+        progress: null,
+        canAutoDownload: true,
+        canApplyInApp: true,
+        requiresRestart: false,
+        blockReason: null,
+        recoveryCommand: null,
+        errorMessage: null,
+        preferences: {
+          automaticChecks: true,
+          autoDownload: true
+        }
+      }
+    });
+
+    renderBrandHeader();
+
+    await user.click(screen.getByRole('button', { name: '更新' }));
+
+    expect(mocks.applyDownloadedUpdate).toHaveBeenCalledTimes(1);
+    expect(mocks.downloadUpdate).not.toHaveBeenCalled();
+  });
+});

package/src/shared/components/common/brand-header.tsx

@@ -1,6 +1,10 @@
+import type { UpdateSnapshot } from '@nextclaw/kernel';
+import { runtimeUpdateManager, useRuntimeUpdateStore } from '@/features/system-status';
 import { useAppMeta } from '@/shared/hooks/use-config';
 import type { ReactNode } from 'react';
 import { RuntimeStatusEntry } from '@/app/components/layout/runtime-status-entry';
+import { cn } from '@/shared/lib/utils';
+import { t } from '@/shared/lib/i18n';
 
 type BrandHeaderProps = {
   className?: string;
@@ -21,8 +25,97 @@ export function BrandHeader({ className, suffix }: BrandHeaderProps) {
       <div className="flex items-baseline gap-2 min-w-0">
         <span className="truncate text-[15px] font-semibold tracking-[-0.01em] text-gray-800">{productName}</span>
         {productVersion ? <span className="text-[13px] font-medium text-gray-500">v{productVersion}</span> : null}
+        <RuntimeUpdateInlineStatus />
         {resolvedSuffix ? <span className="inline-flex items-center shrink-0">{resolvedSuffix}</span> : null}
       </div>
     </div>
   );
 }
+
+function RuntimeUpdateInlineStatus() {
+  const { supported, busyAction, snapshot } = useRuntimeUpdateStore();
+  if (!supported || !snapshot) {
+    return null;
+  }
+  if (snapshot.status === 'downloading' || snapshot.status === 'blocked' || snapshot.status === 'failed') {
+    return <RuntimeUpdateInlineBadge snapshot={snapshot} />;
+  }
+  if (snapshot.status === 'downloaded') {
+    return (
+      <button
+        type="button"
+        className={cn(
+          'inline-flex h-5 shrink-0 items-center rounded-full px-2 text-[11px] font-semibold leading-none ring-1 transition-colors',
+          resolveInlineUpdateTone(snapshot.status)
+        )}
+        disabled={busyAction === 'applying'}
+        onClick={() => void runtimeUpdateManager.applyDownloadedUpdate()}
+      >
+        {busyAction === 'applying' ? t('desktopUpdatesInlineApplying') : t('desktopUpdatesInlineReady')}
+      </button>
+    );
+  }
+  if (snapshot.status === 'update-available') {
+    return (
+      <button
+        type="button"
+        className={cn(
+          'inline-flex h-5 shrink-0 items-center rounded-full px-2 text-[11px] font-semibold leading-none ring-1 transition-colors',
+          resolveInlineUpdateTone(snapshot.status)
+        )}
+        disabled={busyAction === 'downloading'}
+        onClick={() => void runtimeUpdateManager.downloadUpdate()}
+      >
+        {busyAction === 'downloading' ? t('desktopUpdatesInlineDownloading') : t('desktopUpdatesInlineDownload')}
+      </button>
+    );
+  }
+  return null;
+}
+
+function RuntimeUpdateInlineBadge({ snapshot }: { snapshot: UpdateSnapshot }) {
+  const label = resolveInlineUpdateLabel(snapshot);
+  if (!label) {
+    return null;
+  }
+  return (
+    <span
+      className={cn(
+        'inline-flex h-5 shrink-0 items-center rounded-full px-2 text-[11px] font-semibold leading-none ring-1 transition-colors',
+        resolveInlineUpdateTone(snapshot.status)
+      )}
+      title={t('updates')}
+    >
+      {label}
+    </span>
+  );
+}
+
+function resolveInlineUpdateLabel(snapshot: UpdateSnapshot): string | null {
+  if (snapshot.status === 'downloading') {
+    const percent = snapshot.progress?.percent;
+    return percent === null || percent === undefined
+      ? t('desktopUpdatesInlineDownloading')
+      : t('desktopUpdatesInlineDownloadingPercent').replace('{percent}', String(percent));
+  }
+  if (snapshot.status === 'downloaded') {
+    return t('desktopUpdatesInlineReady');
+  }
+  if (snapshot.status === 'update-available') {
+    return t('desktopUpdatesInlineDownload');
+  }
+  if (snapshot.status === 'blocked' || snapshot.status === 'failed') {
+    return t('desktopUpdatesInlineAttention');
+  }
+  return null;
+}
+
+function resolveInlineUpdateTone(status: UpdateSnapshot['status']): string {
+  if (status === 'downloaded') {
+    return 'bg-emerald-50 text-emerald-700 ring-emerald-100 hover:bg-emerald-100 disabled:opacity-70';
+  }
+  if (status === 'blocked' || status === 'failed') {
+    return 'bg-red-50 text-red-700 ring-red-100';
+  }
+  return 'bg-amber-50 text-amber-700 ring-amber-100 hover:bg-amber-100 disabled:opacity-70';
+}

package/src/shared/components/cron-config.tsx

@@ -39,7 +39,7 @@ function formatEveryDuration(ms?: number | null): string {
 }
 
 function describeSchedule(job: CronJobView): string {
-  const schedule = job.schedule;
+  const { schedule } = job;
   if (schedule.kind === 'cron') {
     return schedule.expr ? `cron ${schedule.expr}` : 'cron';
   }
@@ -61,6 +61,10 @@ function describeDelivery(job: CronJobView): string {
   return `${channel}:${target}`;
 }
 
+function describeSession(job: CronJobView): string {
+  return job.payload.sessionId?.trim() || `cron:${job.id}`;
+}
+
 function matchQuery(job: CronJobView, query: string): boolean {
   const q = query.trim().toLowerCase();
   if (!q) return true;
@@ -68,6 +72,7 @@ function matchQuery(job: CronJobView, query: string): boolean {
     job.id,
     job.name,
     job.payload.message,
+    job.payload.sessionId ?? '',
     job.payload.channel ?? '',
     job.payload.to ?? ''
   ].join(' ').toLowerCase();
@@ -104,6 +109,7 @@ function CronJobCard(props: {
             </div>
             <div className="mt-2 text-xs text-gray-500">{t('cronScheduleLabel')}: {describeSchedule(job)}</div>
             <div className="mt-2 whitespace-pre-wrap break-words text-sm text-gray-700">{job.payload.message}</div>
+            <div className="mt-2 text-xs text-gray-500">{t('cronSessionLabel')}: {describeSession(job)}</div>
             <div className="mt-2 text-xs text-gray-500">{t('cronDeliverTo')}: {describeDelivery(job)}</div>
           </div>
           <div className="min-w-[220px] space-y-2 text-xs text-gray-500">

package/src/shared/components/doc-browser/doc-browser-context.test.tsx

@@ -83,7 +83,7 @@ describe('DocBrowserProvider dedupe keys', () => {
         title: 'Skill B',
       });
     });
-    const activeTabId = result.current.activeTabId;
+    const { activeTabId } = result.current;
 
     act(() => {
       result.current.open('data:text/html,A-loaded', {

package/src/shared/components/doc-browser/doc-browser.tsx

@@ -203,7 +203,7 @@ export function DocBrowser({ displayMode = 'desktop' }: DocBrowserProps) {
     e.preventDefault();
     e.stopPropagation();
     setIsResizing(true);
-    const axis = (e.currentTarget as HTMLElement).dataset.axis;
+    const { axis } = (e.currentTarget as HTMLElement).dataset;
     resizeRef.current = {
       startX: e.clientX,
       startY: e.clientY,

package/src/shared/components/search-config.tsx

@@ -179,7 +179,7 @@ function SearchProviderFields(props: {
   const { draft, provider, search, selectedDocsUrl, updateProviderDraft } = props;
 
   if (provider === "bocha") {
-    const bocha = draft.providers.bocha;
+    const { bocha } = draft.providers;
     return (
       <>
         <SearchTextField
@@ -214,7 +214,7 @@ function SearchProviderFields(props: {
   }
 
   if (provider === "tavily") {
-    const tavily = draft.providers.tavily;
+    const { tavily } = draft.providers;
     return (
       <>
         <SearchTextField
@@ -252,7 +252,7 @@ function SearchProviderFields(props: {
     );
   }
 
-  const brave = draft.providers.brave;
+  const { brave } = draft.providers;
   return (
     <>
       <SearchTextField

package/src/shared/lib/api/README.md

@@ -0,0 +1,3 @@
+## 子树边界豁免
+
+- 原因：`shared/lib/api` 是历史形成的前端 API facade，当前同时承载 client、endpoint wrapper、query cache、transport helper 与 response view types。本次新增 `ncp-session.types.ts` 是为了把会话类型从超大的 `types.ts` 中拆出，实际降低核心类型文件体积；完整子树化需要同步改造大量公共导出和调用方，适合单独结构治理批次推进。

package/src/shared/lib/api/index.ts

@@ -10,11 +10,13 @@ export * from './marketplace';
 export * from './mcp-marketplace';
 export * from './ncp-attachments';
 export * from './ncp-session';
+export * from './ncp-session.types';
 export * from './ncp-session-query-cache';
 export * from './raw-client.utils';
 export * from './remote';
 export * from './remote.types';
 export * from './runtime-control';
 export * from './runtime-control.types';
+export * from './runtime-update.service';
 export * from './server-path';
 export * from './types';

package/src/shared/lib/api/ncp-attachments.ts

@@ -6,11 +6,11 @@ function readErrorMessage(payload: unknown, fallback: string): string {
   if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
     return fallback;
   }
-  const error = (payload as { error?: unknown }).error;
+  const { error } = (payload as { error?: unknown });
   if (!error || typeof error !== "object" || Array.isArray(error)) {
     return fallback;
   }
-  const message = (error as { message?: unknown }).message;
+  const { message } = (error as { message?: unknown });
   return typeof message === "string" && message.trim().length > 0 ? message : fallback;
 }