ompchamber 0.3.0

package/src/client/hooks/settings/crud-list.ts

@@ -0,0 +1,187 @@
+import { useEffect, useState } from 'preact/hooks';
+import { invalidateComposerCache } from '@/shared/lib/chat/composer/client';
+
+export interface CrudListMessages {
+  load: string;
+  save: string;
+  delete: string;
+}
+
+/**
+ * Config bag for {@link useCrudList}. The defaults reproduce the plain
+ * agent/command/skill shape (GET list → select first, POST `{ [bodyKey]: item }`
+ * with optimistic upsert, DELETE `?id=` then refetch). Every override exists so
+ * the MCP screen keeps its project-scoped, server-list-only behavior.
+ */
+export interface CrudListConfig<T extends { id: string }, D = T> {
+  endpoint: string;
+  listKey: string;
+  bodyKey: string;
+  /** Extra query string (with leading `?`) appended to GET (and refetch). */
+  query?: string;
+  messages: CrudListMessages;
+  /** Composer cache key invalidated after a successful save/delete. */
+  cacheKey?: string;
+  /** Build the item to persist when creating. */
+  buildNew: (draft: D) => T;
+  /** Build the item to persist when updating. */
+  buildUpdate: (draft: D, selected: T | undefined, selectedId: string | null) => T;
+  /** Custom POST body. Defaults to `{ [bodyKey]: target }`. */
+  buildBody?: (target: T) => unknown;
+  /** Custom DELETE query. Defaults to `?id=${encodeURIComponent(id)}`. */
+  buildDeleteQuery?: (id: string) => string;
+  /** Read the list out of a payload; `null` when absent. Defaults to `data[listKey]`. */
+  readList?: (data: unknown) => T[] | null;
+  /** Resolve selected id after load. Defaults to the first item or `null`. */
+  resolveOnLoad?: (prev: string | null, list: T[]) => string | null;
+  /** Resolve selected id after save. Return `undefined` to leave it untouched. */
+  resolveOnSave?: (target: T, list: T[] | null) => string | null | undefined;
+  /** When true, never optimistically upsert on save. */
+  serverListOnly?: boolean;
+  /** When true, delete uses the response list instead of refetching. */
+  deleteFromResponse?: boolean;
+  /** When false, `selected` is undefined if no id matches. Defaults true. */
+  fallbackToFirst?: boolean;
+  /** Return true to abort save on a payload error (log inside the callback). */
+  isSaveError?: (data: unknown) => boolean;
+  /** Return true to abort delete on a payload error (log inside the callback). */
+  isDeleteError?: (data: unknown) => boolean;
+}
+
+export interface CrudListController<T extends { id: string }, D = T> {
+  items: T[];
+  selectedId: string | null;
+  selected: T | undefined;
+  isCreatingNew: boolean;
+  isLoading: boolean;
+  select: (id: string) => void;
+  startCreate: () => void;
+  save: (draft: D) => void;
+  remove: (id: string) => void;
+}
+
+function defaultReadList<T>(listKey: string) {
+  return (data: unknown): T[] | null => {
+    const value = (data as Record<string, unknown> | null | undefined)?.[listKey];
+    return Array.isArray(value) ? (value as T[]) : null;
+  };
+}
+
+/** Shared load/save/delete + selection controller for the settings CRUD screens. */
+export function useCrudList<T extends { id: string }, D = T>(
+  config: CrudListConfig<T, D>,
+): CrudListController<T, D> {
+  const { endpoint, listKey, query, messages, cacheKey } = config;
+  const [items, setItems] = useState<T[]>([]);
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  const [isCreatingNew, setIsCreatingNew] = useState(false);
+  const [isLoading, setIsLoading] = useState(true);
+
+  const readList = config.readList ?? defaultReadList<T>(listKey);
+
+  useEffect(() => {
+    let active = true;
+    fetch(`${endpoint}${query ?? ''}`)
+      .then((res) => res.json())
+      .then((data) => {
+        if (!active) return;
+        const list = readList(data) ?? [];
+        setItems(list);
+        setSelectedId((prev) =>
+          config.resolveOnLoad ? config.resolveOnLoad(prev, list) : list.length > 0 ? list[0].id : null,
+        );
+      })
+      .catch((err) => console.error(messages.load, err))
+      .finally(() => {
+        if (active) setIsLoading(false);
+      });
+    return () => {
+      active = false;
+    };
+  }, [endpoint, query]);
+
+  const selected =
+    config.fallbackToFirst === false
+      ? items.find((item) => item.id === selectedId)
+      : items.find((item) => item.id === selectedId) ?? items[0];
+
+  const select = (id: string) => {
+    setIsCreatingNew(false);
+    setSelectedId(id);
+  };
+
+  const startCreate = () => {
+    setIsCreatingNew(true);
+    setSelectedId(null);
+  };
+
+  const save = (draft: D) => {
+    const target = isCreatingNew
+      ? config.buildNew(draft)
+      : config.buildUpdate(draft, selected, selectedId);
+    const body = config.buildBody ? config.buildBody(target) : { [config.bodyKey]: target };
+    fetch(endpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    })
+      .then((res) => res.json())
+      .then((data) => {
+        if (config.isSaveError?.(data)) return;
+        const list = readList(data);
+        if (list) {
+          setItems(list);
+        } else if (!config.serverListOnly) {
+          setItems((prev) => {
+            const exists = prev.some((item) => item.id === target.id);
+            return exists
+              ? prev.map((item) => (item.id === target.id ? target : item))
+              : [...prev, target];
+          });
+        }
+        const nextId = config.resolveOnSave ? config.resolveOnSave(target, list) : target.id;
+        if (nextId !== undefined) setSelectedId(nextId);
+        setIsCreatingNew(false);
+        if (cacheKey) invalidateComposerCache(cacheKey);
+      })
+      .catch((err) => console.error(messages.save, err));
+  };
+
+  const remove = (id: string) => {
+    const deleteQuery = config.buildDeleteQuery
+      ? config.buildDeleteQuery(id)
+      : `?id=${encodeURIComponent(id)}`;
+    fetch(`${endpoint}${deleteQuery}`, { method: 'DELETE' })
+      .then((res) => res.json())
+      .then((data) => {
+        if (config.isDeleteError?.(data)) return;
+        if (cacheKey) invalidateComposerCache(cacheKey);
+        if (config.deleteFromResponse) {
+          const list = readList(data) ?? items.filter((item) => item.id !== id);
+          setItems(list);
+          if (selectedId === id) setSelectedId(list[0]?.id ?? null);
+        } else {
+          fetch(`${endpoint}${query ?? ''}`)
+            .then((r) => r.json())
+            .then((d) => {
+              const next = readList(d) ?? [];
+              setItems(next);
+              if (selectedId === id) setSelectedId(next[0]?.id || null);
+            });
+        }
+      })
+      .catch((err) => console.error(messages.delete, err));
+  };
+
+  return {
+    items,
+    selectedId,
+    selected,
+    isCreatingNew,
+    isLoading,
+    select,
+    startCreate,
+    save,
+    remove,
+  };
+}

package/src/client/hooks/settings/instruction-file.ts

@@ -0,0 +1,91 @@
+import { useCallback, useEffect, useState } from 'preact/hooks';
+import type { InstructionFileKind, InstructionFilePayload, InstructionSaveResult } from '@/shared/types';
+
+export interface InstructionFileState {
+  content: string;
+  /** Absolute native path, or null in MOCK mode where nothing hits disk. */
+  filePath: string | null;
+  exists: boolean;
+  isMock: boolean;
+  isLoading: boolean;
+  error: string | null;
+  save: (content: string) => Promise<InstructionSaveResult>;
+  reset: () => Promise<InstructionSaveResult>;
+}
+
+/**
+ * One native user instruction file (AGENTS.md / RULES.md) behind the Behavior
+ * panel: loads the file when the panel mounts and persists edits back to it,
+ * reporting either the failure or what else the save wrote.
+ */
+export function useInstructionFile(kind: InstructionFileKind): InstructionFileState {
+  const [content, setContent] = useState('');
+  const [filePath, setFilePath] = useState<string | null>(null);
+  const [exists, setExists] = useState(false);
+  const [isMock, setIsMock] = useState(false);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const adopt = useCallback((data: InstructionFilePayload) => {
+    if (typeof data.rules === 'string') setContent(data.rules);
+    setFilePath(typeof data.path === 'string' ? data.path : null);
+    setExists(data.exists === true);
+    setIsMock(data.isMock === true);
+  }, []);
+
+  useEffect(() => {
+    let active = true;
+    setError(null);
+    fetch(`/api/settings/behavior?file=${kind}`)
+      .then((res) => res.json() as Promise<InstructionFilePayload>)
+      .then((data) => {
+        if (!active) return;
+        if (data.error) {
+          setError(data.error);
+          return;
+        }
+        adopt(data);
+      })
+      .catch((err) => {
+        if (active) setError(err instanceof Error ? err.message : String(err));
+      })
+      .finally(() => {
+        if (active) setIsLoading(false);
+      });
+    return () => {
+      active = false;
+    };
+  }, [adopt, kind]);
+
+  const persist = useCallback(
+    async (body: Record<string, unknown>): Promise<InstructionSaveResult> => {
+      try {
+        const res = await fetch('/api/settings/behavior', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ ...body, file: kind }),
+        });
+        const data = (await res.json()) as InstructionFilePayload;
+        if (data.error) return { error: data.error };
+        adopt(data);
+        if (data.nativeError) return { note: `Saved, but the approval mapping was skipped: ${data.nativeError}` };
+        if (data.nativeSynced) return { note: 'Saved — recognized permission gates were mirrored into config.yml tools.approval.' };
+        return {};
+      } catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+      }
+    },
+    [adopt, kind],
+  );
+
+  return {
+    content,
+    filePath,
+    exists,
+    isMock,
+    isLoading,
+    error,
+    save: (next: string) => persist({ rules: next }),
+    reset: () => persist({ action: 'reset' }),
+  };
+}

package/src/client/hooks/settings/providers.ts

@@ -0,0 +1,295 @@
+import { useEffect, useMemo, useState } from 'preact/hooks';
+import type { PresetProviderOption, ProviderItem, ProviderModel } from '@/shared/types';
+import { PRESET_NEW_PROVIDERS } from '@/client/data/settings/provider';
+import { fetchProviderModelsRemote, mergeProviderModels, syncProviderModelsToCatalog } from '@/shared/lib/models/provider-models';
+import { buildAvailableProviderPresets } from '@/shared/lib/models/provider-presets';
+import { removeLegacyKenariModels } from '@/shared/lib/models/provider-cleanup';
+import { notifyModelsUpdated } from '@/shared/lib/models/client';
+import { saveProviderOverlay, setProviderEnabled } from '@/shared/lib/models/provider-connection';
+import { useToasts } from '@/client/hooks/ui/toasts';
+
+interface UseProviderSettingsOptions {
+  autoOpenAdd?: boolean;
+  onAddModalClose?: () => void;
+}
+
+/**
+ * State and actions behind Settings → Providers. Every mutation lands in one of
+ * two stores: the chamber-local overlay (per-model visibility and sampling
+ * config) or omp's own config.yml disabledProviders (connect / disconnect).
+ * Disconnect has to use the latter — the overlay is re-merged away on load,
+ * which is why a disconnected provider used to come back as connected.
+ */
+export function useProviderSettings({
+  autoOpenAdd = false,
+  onAddModalClose,
+}: UseProviderSettingsOptions = {}) {
+  const [providers, setProviders] = useState<ProviderItem[]>([]);
+  const [presetProviders, setPresetProviders] = useState<PresetProviderOption[]>(PRESET_NEW_PROVIDERS);
+  const [selectedProviderId, setSelectedProviderId] = useState<string>('provider-deepseek');
+  const [currentProject, setCurrentProject] = useState('ompchamber');
+  const [isFetchingModels, setIsFetchingModels] = useState(false);
+  const { toasts, pushToast, dismissToast } = useToasts();
+
+  const [isAddModalOpen, setIsAddModalOpen] = useState(autoOpenAdd);
+  const [isReconnectModalOpen, setIsReconnectModalOpen] = useState(false);
+  const [isLoginModalOpen, setIsLoginModalOpen] = useState(false);
+  const [configModel, setConfigModel] = useState<ProviderModel | null>(null);
+  const [capabilitiesModel, setCapabilitiesModel] = useState<ProviderModel | null>(null);
+
+  useEffect(() => {
+    if (autoOpenAdd) setIsAddModalOpen(true);
+  }, [autoOpenAdd]);
+
+  useEffect(() => {
+    let active = true;
+    fetch('/api/settings/providers')
+      .then(res => res.json())
+      .then(data => {
+        if (!active) return;
+        if (data?.providers && Array.isArray(data.providers)) {
+          setProviders(data.providers);
+          const connected = data.providers.filter((p: ProviderItem) => p.status === 'connected');
+          setSelectedProviderId(connected.length > 0 ? connected[0].id : '');
+        }
+        if (data?.presetProviders) setPresetProviders(data.presetProviders);
+      })
+      .catch(err => console.error('Failed to load providers from API:', err));
+    return () => { active = false; };
+  }, []);
+
+  // The sidebar lists connected providers plus every provider the user disabled:
+  // a disabled provider reports `disconnected`, so filtering on status alone
+  // would make the switch that hid it unreachable.
+  const connectedProviders = useMemo(
+    () => providers.filter(
+      (provider) => provider.status === 'connected' || provider.disabled === true,
+    ),
+    [providers],
+  );
+  const availablePresetProviders = useMemo(
+    () => buildAvailableProviderPresets(providers, presetProviders),
+    [providers, presetProviders],
+  );
+  const selectedProvider = connectedProviders.find((p) => p.id === selectedProviderId) || connectedProviders[0];
+
+  const persistProviders = async (updated: ProviderItem[]) => {
+    setProviders(updated);
+    try {
+      const merged = await saveProviderOverlay(updated);
+      if (merged) setProviders(merged);
+    } catch (err) {
+      console.error('Failed to save providers via API:', err);
+      pushToast('Failed to save provider settings.', 'error');
+    }
+  };
+
+  const toggleProviderEnabled = async (
+    slug: string,
+    enabled: boolean,
+  ): Promise<ProviderItem[] | null> => {
+    try {
+      const merged = await setProviderEnabled(slug, enabled);
+      if (merged) setProviders(merged);
+      return merged;
+    } catch (err) {
+      console.error('Failed to update provider connection:', err);
+      pushToast('Failed to update the provider connection.', 'error');
+      return null;
+    }
+  };
+
+  const handleAddProvider = async (newProvider: ProviderItem, options: { fetchedCount: number }) => {
+    await persistProviders([...providers, newProvider]);
+    const merged = await toggleProviderEnabled(newProvider.slug, true);
+    const registered = merged?.find(
+      (provider) => provider.slug.trim().toLowerCase() === newProvider.slug.trim().toLowerCase(),
+    );
+    setSelectedProviderId(registered?.id || newProvider.id);
+    setIsAddModalOpen(false);
+    onAddModalClose?.();
+
+    if (options.fetchedCount > 0) {
+      pushToast(
+        `Fetched ${options.fetchedCount} new model${options.fetchedCount === 1 ? '' : 's'} from the provider.`,
+        'success',
+      );
+    } else if (options.fetchedCount === -1) {
+      pushToast('Auto-fetch models failed — provider added with default models.', 'error');
+    }
+
+    void syncProviderModelsToCatalog(newProvider.name, newProvider.models);
+  };
+
+  const handleReconnect = async (updates: Partial<ProviderItem>) => {
+    if (!selectedProvider) return;
+    const target = selectedProvider;
+    await persistProviders(providers.map((p) => (
+      p.id === target.id ? { ...p, ...updates, status: 'connected' as const } : p
+    )));
+    if (target.status !== 'connected') {
+      await toggleProviderEnabled(target.slug, true);
+    }
+  };
+
+  const handleFetchModels = async (credentials: { apiKey?: string; baseUrl?: string }) => {
+    if (!selectedProvider || isFetchingModels) return;
+    const baseUrl = credentials.baseUrl || selectedProvider.baseUrl;
+    if (!baseUrl) {
+      pushToast('Base URL is required to fetch models.', 'error');
+      return;
+    }
+    setIsFetchingModels(true);
+    try {
+      const result = await fetchProviderModelsRemote(
+        baseUrl,
+        credentials.apiKey || selectedProvider.apiKey,
+        selectedProvider.slug,
+        true,
+      );
+      if (!result.ok || !result.models) {
+        pushToast(result.error || 'Failed to fetch models from the provider.', 'error');
+        return;
+      }
+      const cleanedExistingModels = removeLegacyKenariModels(selectedProvider, selectedProvider.models);
+      const removedCount = selectedProvider.models.length - cleanedExistingModels.length;
+      const { merged, addedCount } = mergeProviderModels(cleanedExistingModels, result.models);
+      if (addedCount > 0 || removedCount > 0) {
+        await handleReconnect({ models: merged });
+      }
+      if (result.omp?.written) {
+        notifyModelsUpdated();
+      }
+      if (addedCount > 0) {
+        pushToast(`Fetched ${addedCount} new model${addedCount === 1 ? '' : 's'} from the provider.`, 'success');
+      } else if (removedCount > 0) {
+        pushToast('Removed legacy fallback models from the provider.', 'success');
+      } else {
+        pushToast('No new models found — all fetched models already exist.', 'success');
+      }
+      if (result.omp?.written) {
+        const parts: string[] = [];
+        if (result.omp.addedCount > 0) parts.push(`${result.omp.addedCount} new model${result.omp.addedCount === 1 ? '' : 's'} registered`);
+        if (result.omp.backfilledCount > 0) parts.push(`${result.omp.backfilledCount} model${result.omp.backfilledCount === 1 ? '' : 's'} enriched`);
+        pushToast(`omp models.yml updated${parts.length > 0 ? `: ${parts.join(', ')}` : ''}.`, 'success');
+      } else if (result.omp && !result.omp.written && result.omp.reason) {
+        pushToast(`omp models.yml not updated: ${result.omp.reason}`, 'error');
+      }
+    } finally {
+      setIsFetchingModels(false);
+    }
+  };
+
+  const handleFetchModelsFromList = async () => {
+    if (!selectedProvider) return;
+    await handleFetchModels({
+      apiKey: selectedProvider.apiKey,
+      baseUrl: selectedProvider.baseUrl,
+    });
+  };
+
+  const handleOmpAuthSuccess = () => {
+    if (!selectedProvider) return;
+    const target = selectedProvider;
+    void persistProviders(providers.map((p) => (
+      p.id === target.id ? { ...p, status: 'connected' as const } : p
+    )));
+    void toggleProviderEnabled(target.slug, true);
+  };
+
+  const handleToggleDisconnect = async () => {
+    if (!selectedProvider) return;
+    const target = selectedProvider;
+    const disconnecting = target.status === 'connected';
+    if (disconnecting) {
+      setSelectedProviderId(
+        connectedProviders.find((provider) => provider.id !== target.id)?.id || '',
+      );
+    }
+    const merged = await toggleProviderEnabled(target.slug, !disconnecting);
+    if (!merged) return;
+    pushToast(
+      disconnecting
+        ? `${target.name} disconnected — its models are no longer offered in the chat picker.`
+        : `${target.name} reconnected.`,
+      'success',
+    );
+  };
+
+  const updateSelectedModels = (transform: (models: ProviderModel[]) => ProviderModel[]) => {
+    if (!selectedProvider) return;
+    void persistProviders(providers.map((p) => (
+      p.id === selectedProvider.id ? { ...p, models: transform(p.models) } : p
+    )));
+  };
+
+  /**
+   * Disable/enable from omp's own config.yml `disabledProviders`. This is the
+   * coarse switch that removes the provider — and every model it serves — from
+   * the chat picker; the per-model eye toggle is the fine-grained one.
+   */
+  const handleToggleProviderDisabled = async () => {
+    if (!selectedProvider) return;
+    const target = selectedProvider;
+    const disabling = target.disabled !== true;
+    const merged = await toggleProviderEnabled(target.slug, !disabling);
+    if (!merged) return;
+    pushToast(
+      disabling
+        ? `${target.name} disabled — it no longer appears in the model list.`
+        : `${target.name} enabled — its models are offered again.`,
+      'success',
+    );
+  };
+
+  const handleHideAll = () => updateSelectedModels(
+    (models) => models.map((m) => ({ ...m, isVisible: false })),
+  );
+
+  const handleShowAll = () => updateSelectedModels(
+    (models) => models.map((m) => ({ ...m, isVisible: true })),
+  );
+
+  const handleToggleModelVisibility = (modelId: string) => updateSelectedModels(
+    (models) => models.map((m) => (m.id === modelId ? { ...m, isVisible: !m.isVisible } : m)),
+  );
+
+  const handleSaveModelConfig = (modelId: string, updates: Partial<ProviderModel>) => updateSelectedModels(
+    (models) => models.map((m) => (m.id === modelId ? { ...m, ...updates } : m)),
+  );
+
+  return {
+    providers,
+    connectedProviders,
+    availablePresetProviders,
+    selectedProvider,
+    currentProject,
+    setCurrentProject,
+    isFetchingModels,
+    toasts,
+    pushToast,
+    dismissToast,
+    isAddModalOpen,
+    setIsAddModalOpen,
+    isReconnectModalOpen,
+    setIsReconnectModalOpen,
+    isLoginModalOpen,
+    setIsLoginModalOpen,
+    configModel,
+    setConfigModel,
+    capabilitiesModel,
+    setCapabilitiesModel,
+    setSelectedProviderId,
+    handleAddProvider,
+    handleReconnect,
+    handleFetchModels,
+    handleFetchModelsFromList,
+    handleOmpAuthSuccess,
+    handleToggleDisconnect,
+    handleToggleProviderDisabled,
+    handleHideAll,
+    handleShowAll,
+    handleToggleModelVisibility,
+    handleSaveModelConfig,
+  };
+}

package/src/client/hooks/settings/skill-catalog.ts

@@ -0,0 +1,37 @@
+import { useCallback, useEffect, useState } from 'preact/hooks';
+import type { Dispatch, StateUpdater } from 'preact/hooks';
+import type { CatalogSkillItem, SkillCatalogSource, SkillItem } from '@/shared/types';
+
+export interface SkillCatalogData {
+  sources: SkillCatalogSource[];
+  catalogSkills: CatalogSkillItem[];
+  userSkills: SkillItem[];
+  setSources: Dispatch<StateUpdater<SkillCatalogSource[]>>;
+  setUserSkills: Dispatch<StateUpdater<SkillItem[]>>;
+  reload: () => Promise<void>;
+}
+
+/**
+ * Catalog dataset behind the skill catalog screen. The initial load and the
+ * manual refresh hit the same endpoint and set the same three slices, so both
+ * go through `reload`; each call site keeps its own toast/error handling.
+ */
+export function useSkillCatalog(): SkillCatalogData {
+  const [sources, setSources] = useState<SkillCatalogSource[]>([]);
+  const [catalogSkills, setCatalogSkills] = useState<CatalogSkillItem[]>([]);
+  const [userSkills, setUserSkills] = useState<SkillItem[]>([]);
+
+  const reload = useCallback(async () => {
+    const res = await fetch('/api/settings/skills');
+    const data = await res.json();
+    if (data?.catalogSources) setSources(data.catalogSources);
+    if (data?.catalogSkills) setCatalogSkills(data.catalogSkills);
+    if (data?.skills) setUserSkills(data.skills);
+  }, []);
+
+  useEffect(() => {
+    reload().catch(console.error);
+  }, [reload]);
+
+  return { sources, catalogSkills, userSkills, setSources, setUserSkills, reload };
+}

package/src/client/hooks/settings/use-chamber-setting.ts

@@ -0,0 +1,12 @@
+import { useCallback } from 'preact/hooks';
+import { writeChamberSettings } from '@/shared/lib/settings/client';
+
+/**
+ * Stable writer for the chamber settings blob: applies the patch to the
+ * in-memory snapshot, then persists the merged blob to SQLite.
+ */
+export function useChamberSettingsWriter(): (patch: Record<string, any>) => void {
+  return useCallback((patch: Record<string, any>) => {
+    writeChamberSettings(patch);
+  }, []);
+}

package/src/client/hooks/settings/useUsageReport.ts

@@ -0,0 +1,41 @@
+import { useCallback, useEffect, useState } from 'preact/hooks';
+import type { UsageReport } from '@/shared/types';
+
+export interface UsageReportState {
+  report: UsageReport | null;
+  isLoading: boolean;
+  error: string | null;
+  reload: (opts?: { silent?: boolean }) => void;
+}
+
+/**
+ * Shared `GET /api/settings/usage` loader for the Settings → Usage panel and
+ * the Usage right panel. Both surfaces mount independently, so each keeps its
+ * own copy of the last successful report until reload completes.
+ */
+export function useUsageReport(): UsageReportState {
+  const [report, setReport] = useState<UsageReport | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const reload = useCallback(async (opts?: { silent?: boolean }) => {
+    if (!opts?.silent) setIsLoading(true);
+    setError(null);
+    try {
+      const response = await fetch('/api/settings/usage');
+      if (!response.ok) throw new Error(`Usage request failed (${response.status})`);
+      const data = (await response.json()) as UsageReport;
+      setReport(data);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to load provider usage');
+    } finally {
+      if (!opts?.silent) setIsLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    void reload();
+  }, [reload]);
+
+  return { report, isLoading, error, reload };
+}