Your lightweight open-source personal agent.
Python agent-frameworkai-agentai-agentschatbotchatopsdiscord-botllm-agentsllmslocal-llmmcpmodel-context-protocolmulti-agentopenai-compatibleopenclawpersonal-ai-assistantpythonself-hostedtelegram-bot-ai-assistantwebuiworkflow-automation
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { useTranslation } from "react-i18next";
import { imageGenerationFormFromPayload } from "@/components/settings/capabilities/ImageGenerationSettings";
import {
networkSafetyFormFromPayload,
visibleWebuiDefaultAccessMode,
} from "@/components/settings/capabilities/SecuritySettings";
import {
DEFAULT_TRANSCRIPTION_SETTINGS,
transcriptionFormFromPayload,
} from "@/components/settings/capabilities/TranscriptionSettings";
import { useCapabilitySettingsActions } from "@/components/settings/capabilities/useCapabilitySettingsActions";
import { useCapabilitySettingsState } from "@/components/settings/capabilities/useCapabilitySettingsState";
import { webSearchDraftState, webSearchFormFromPayload } from "@/components/settings/capabilities/WebSettings";
import type {
ApplySettingsPayload,
PendingRestartSections,
RestartAwarePayload,
SettingsSectionKey,
} from "@/components/settings/contracts";
import { agentDraftFromPayload } from "@/components/settings/models/ModelsSettings";
import { modelAPISelection } from "@/components/settings/models/modelAPI";
import { providerJsonValue } from "@/components/settings/models/providerForm";
import { useModelSettingsActions } from "@/components/settings/models/useModelSettingsActions";
import {
useProviderFormsSync,
useProviderOAuthPolling,
} from "@/components/settings/models/useModelSettingsEffects";
import { useModelSettingsState } from "@/components/settings/models/useModelSettingsState";
import { normalizeContextWindowTokens } from "@/components/settings/shared/ModelControls";
import { useRuntimeConfigSettings } from "@/components/settings/system/RuntimeConfigSettings";
import { createSystemSettingsActions } from "@/components/settings/system/createSystemSettingsActions";
import { useSystemSettingsEffects } from "@/components/settings/system/useSystemSettingsEffects";
import { useSystemSettingsState } from "@/components/settings/system/useSystemSettingsState";
import { getToolsCatalog } from "@/lib/tools-catalog-cache";
import { usePageVisibility } from "@/hooks/usePageVisibility";
import { useEditCompletion } from "@/components/settings/shared/useEditCompletion";
import { cancelProviderOAuth, fetchSettings, fetchSettingsUsage } from "@/lib/api";
import {
LOCAL_PREFS_CHANGED_EVENT,
readLocalPreferences,
writeLocalPreferences,
type LocalPreferences,
} from "@/lib/local-preferences";
import { isLoopbackHost } from "@/lib/network";
import type { SettingsPayload } from "@/lib/types";
import { useClient } from "@/providers/ClientProvider";
interface SettingsControllerOptions {
initialSection: SettingsSectionKey;
initialSettings: SettingsPayload | null;
onModelNameChange: (modelName: string | null) => void;
onSettingsChange?: (payload: SettingsPayload) => void;
onSectionChange?: (section: SettingsSectionKey) => void;
onRestart?: () => void;
onNativeEngineRestart?: () => Promise<string>;
}
const EMPTY_PENDING_RESTART_SECTIONS: PendingRestartSections = {
runtime: false,
browser: false,
image: false,
};
function pendingRestartSectionsFromPayload(payload: SettingsPayload): PendingRestartSections {
const sections = payload.restart_required_sections ?? [];
return {
runtime: sections.includes("runtime"),
browser: sections.includes("browser"),
image: sections.includes("image"),
};
}
export function useSettingsController({
initialSection,
initialSettings,
onModelNameChange,
onSettingsChange,
onSectionChange,
onRestart,
onNativeEngineRestart,
}: SettingsControllerOptions) {
const { t } = useTranslation();
const { client, getToken, token } = useClient();
const pageVisible = usePageVisibility();
const remoteBrowserAccess =
typeof window !== "undefined" && !isLoopbackHost(window.location.hostname);
const [settings, setSettings] = useState<SettingsPayload | null>(() => initialSettings);
const [loading, setLoading] = useState(() => initialSettings === null);
const [hostEngineApplying, setHostEngineApplying] = useState(false);
const [error, setError] = useState<string | null>(null);
const [activeSection, setActiveSection] = useState<SettingsSectionKey>(initialSection);
const [pendingRestartSections, setPendingRestartSections] = useState<PendingRestartSections>(
EMPTY_PENDING_RESTART_SECTIONS,
);
const previousInitialSettingsRef = useRef(initialSettings);
const latestInitialSettingsRef = useRef(initialSettings);
latestInitialSettingsRef.current = initialSettings;
const restartRefreshRef = useRef<SettingsPayload | null>(null);
const [localPrefs, setLocalPrefs] = useState<LocalPreferences>(() => readLocalPreferences());
const modelState = useModelSettingsState(initialSettings);
const {
form, modelPresetEditingName, providerOAuthFlowRef, setForm,
setModelCallOrder, setModelPresetCreating, setModelPresetEditingName,
setProviderOAuthCompleting, setProviderOAuthDialogError,
setProviderOAuthFlow, setProviderOAuthResponse,
} = modelState;
const capabilityState = useCapabilitySettingsState(initialSettings);
const {
imageGenerationForm, networkSafetyForm,
setImageGenerationForm, setNetworkSafetyForm, setTranscriptionForm, setWebSearchForm,
transcriptionForm, webSearchForm,
} = capabilityState;
const draftsRef = useRef({ form, imageGenerationForm, networkSafetyForm, transcriptionForm, webSearchForm });
draftsRef.current = { form, imageGenerationForm, networkSafetyForm, transcriptionForm, webSearchForm };
const systemState = useSystemSettingsState(getToolsCatalog(client, token));
const featureCatalog = systemState.nanobotFeatures?.features ?? [];
useEffect(() => {
setActiveSection(initialSection);
}, [initialSection]);
const selectSection = useCallback(
(section: SettingsSectionKey) => {
setActiveSection(section);
onSectionChange?.(section);
},
[onSectionChange],
);
const applyPayload: ApplySettingsPayload = useCallback(
(
payload: SettingsPayload,
options: { preserveAgentForm?: boolean; preserveCapabilityForms?: boolean } = {},
) => {
setSettings(payload);
if (!options.preserveAgentForm) {
const nextForm = agentDraftFromPayload(payload);
setForm(nextForm);
setModelPresetEditingName(nextForm.modelPreset);
setModelPresetCreating(false);
}
setModelCallOrder(payload.model_call_order ?? []);
if (!options.preserveCapabilityForms) {
setWebSearchForm((prev) => webSearchFormFromPayload(payload, prev));
setImageGenerationForm(imageGenerationFormFromPayload(payload));
setTranscriptionForm(transcriptionFormFromPayload(payload));
setNetworkSafetyForm(networkSafetyFormFromPayload(payload));
}
if (payload.restart_required_sections) {
setPendingRestartSections(pendingRestartSectionsFromPayload(payload));
}
onSettingsChange?.(payload);
},
[onSettingsChange],
);
const runtimeConfigState = useRuntimeConfigSettings(settings, client, applyPayload);
const closeProviderOAuthFlow = useCallback((cancelPending = true) => {
const flow = providerOAuthFlowRef.current;
providerOAuthFlowRef.current = null;
if (cancelPending && flow?.completion_input === "device_code") {
void cancelProviderOAuth(client, flow.provider, flow.flow_id).catch(() => {});
}
setProviderOAuthFlow(null);
setProviderOAuthResponse("");
setProviderOAuthCompleting(false);
setProviderOAuthDialogError(null);
}, [client]);
useProviderOAuthPolling({
state: modelState,
client,
applyPayload,
setError,
closeProviderOAuthFlow,
});
useEffect(() => {
if (!initialSettings || settings !== null) return;
applyPayload(initialSettings);
setLoading(false);
}, [applyPayload, initialSettings, settings]);
useEffect(() => {
const previous = previousInitialSettingsRef.current;
previousInitialSettingsRef.current = initialSettings;
if (previous?.requires_restart && !initialSettings?.requires_restart) {
restartRefreshRef.current = initialSettings;
} else if (restartRefreshRef.current !== initialSettings) {
restartRefreshRef.current = null;
}
const shouldApplyRestartedSettings =
restartRefreshRef.current === initialSettings && settings?.requires_restart === true;
if (!shouldApplyRestartedSettings || !initialSettings) {
return;
}
applyPayload(initialSettings, { preserveAgentForm: true, preserveCapabilityForms: true });
}, [applyPayload, initialSettings, settings]);
useEffect(() => {
let cancelled = false;
const showLoading = settings === null;
const requestInitialSettings = latestInitialSettingsRef.current;
const requestDrafts = draftsRef.current;
if (showLoading) setLoading(true);
fetchSettings(getToken())
.then((payload) => {
if (!cancelled && latestInitialSettingsRef.current === requestInitialSettings) {
const current = draftsRef.current;
applyPayload(payload, {
preserveAgentForm: current.form !== requestDrafts.form,
preserveCapabilityForms: current.imageGenerationForm !== requestDrafts.imageGenerationForm ||
current.networkSafetyForm !== requestDrafts.networkSafetyForm ||
current.transcriptionForm !== requestDrafts.transcriptionForm || current.webSearchForm !== requestDrafts.webSearchForm,
});
setError(null);
}
})
.catch((err) => {
if (!cancelled && showLoading) setError((err as Error).message);
})
.finally(() => {
if (!cancelled) {
setLoading(false);
}
});
return () => {
cancelled = true;
};
}, [applyPayload, getToken]);
const hasSettings = settings !== null;
useEffect(() => {
if (activeSection !== "overview" || !hasSettings || !pageVisible) return;
let cancelled = false;
let refreshing = false;
const refresh = async () => {
if (refreshing) return;
refreshing = true;
try {
const usage = await fetchSettingsUsage(getToken());
if (!cancelled) {
setSettings((current) => (current ? { ...current, usage } : current));
}
} catch {
// Usage is best-effort telemetry; the settings snapshot remains usable.
} finally {
refreshing = false;
}
};
void refresh();
const interval = window.setInterval(() => void refresh(), 5000);
const onFocus = () => void refresh();
window.addEventListener("focus", onFocus);
return () => {
cancelled = true;
window.clearInterval(interval);
window.removeEventListener("focus", onFocus);
};
}, [activeSection, getToken, hasSettings, pageVisible]);
const { refreshAutomations } = useSystemSettingsEffects({
state: systemState,
activeSection,
getToken,
pageVisible,
});
useEffect(() => {
const synchronize = (event: Event) => setLocalPrefs((event as CustomEvent<LocalPreferences>).detail);
const reload = () => setLocalPrefs(readLocalPreferences());
window.addEventListener(LOCAL_PREFS_CHANGED_EVENT, synchronize);
window.addEventListener("storage", reload);
window.addEventListener("focus", reload);
return () => {
window.removeEventListener(LOCAL_PREFS_CHANGED_EVENT, synchronize);
window.removeEventListener("storage", reload);
window.removeEventListener("focus", reload);
};
}, []);
useEffect(() => {
writeLocalPreferences(localPrefs);
}, [localPrefs]);
useProviderFormsSync(modelState, settings);
const modelDirty = useMemo(() => {
if (!settings) return false;
const selectedPreset = settings.model_presets.find(
(preset) => !preset.is_default && preset.name === modelPresetEditingName,
);
if (!selectedPreset) return false;
return (
form.modelPreset !== selectedPreset.name ||
form.model !== selectedPreset.model ||
form.provider !== selectedPreset.provider ||
form.maxTokens !== selectedPreset.max_tokens ||
form.contextWindowTokens !== normalizeContextWindowTokens(selectedPreset.context_window_tokens) ||
form.temperature !== selectedPreset.temperature ||
form.reasoningEffort !== (selectedPreset.reasoning_effort ?? "") ||
modelAPISelection(form.api) !== modelAPISelection(selectedPreset.api) ||
form.extraHeaders !== providerJsonValue(selectedPreset.extra_headers) ||
form.extraQuery !== providerJsonValue(selectedPreset.extra_query) ||
form.extraBody !== providerJsonValue(selectedPreset.extra_body)
);
}, [form, modelPresetEditingName, settings]);
const imageGenerationDirty = useMemo(() => {
if (!settings) return false;
return (
imageGenerationForm.enabled !== settings.image_generation.enabled ||
imageGenerationForm.provider !== settings.image_generation.provider ||
imageGenerationForm.model !== settings.image_generation.model ||
imageGenerationForm.defaultAspectRatio !== settings.image_generation.default_aspect_ratio ||
imageGenerationForm.defaultImageSize !== settings.image_generation.default_image_size ||
imageGenerationForm.maxImagesPerTurn !== settings.image_generation.max_images_per_turn ||
(settings.image_generation.request_overrides_supported && (
imageGenerationForm.extraHeaders !== providerJsonValue(settings.image_generation.extra_headers) ||
imageGenerationForm.extraBody !== providerJsonValue(settings.image_generation.extra_body)
)) === true
);
}, [imageGenerationForm, settings]);
const transcriptionDirty = useMemo(() => {
if (!settings) return false;
const transcription = settings.transcription ?? DEFAULT_TRANSCRIPTION_SETTINGS;
return (
transcriptionForm.enabled !== transcription.enabled ||
transcriptionForm.provider !== transcription.provider ||
transcriptionForm.model !== transcription.model ||
transcriptionForm.language !== (transcription.language ?? "") ||
transcriptionForm.maxDurationSec !== transcription.max_duration_sec ||
transcriptionForm.maxUploadMb !== transcription.max_upload_mb
);
}, [settings, transcriptionForm]);
const networkSafetyDirty = useMemo(() => {
if (!settings) return false;
const currentLocalServiceAccess =
settings.advanced.webui_allow_local_service_access ?? settings.advanced.allow_local_preview_access ?? true;
const currentDefaultAccess = visibleWebuiDefaultAccessMode(settings.advanced.webui_default_access_mode);
return (
networkSafetyForm.webuiAllowLocalServiceAccess !== currentLocalServiceAccess ||
networkSafetyForm.webuiDefaultAccessMode !== currentDefaultAccess
);
}, [networkSafetyForm, settings]);
const configuredModelProviderOptions = useMemo(
() =>
settings?.providers
.filter((provider) => provider.configured && provider.model_selectable !== false)
.map((provider) => ({ name: provider.name, label: provider.label })) ?? [],
[settings],
);
const restartViaSettingsSurface = useCallback(async () => {
const isNativeHost = (settings?.surface ?? settings?.runtime_surface) === "native";
if (
isNativeHost &&
settings?.runtime_capabilities?.can_restart_engine &&
onNativeEngineRestart
) {
setHostEngineApplying(true);
const requestDrafts = draftsRef.current;
try {
const nextToken = await onNativeEngineRestart();
const payload = await fetchSettings(nextToken);
const current = draftsRef.current;
applyPayload(payload, {
preserveAgentForm: current.form !== requestDrafts.form,
preserveCapabilityForms: current.imageGenerationForm !== requestDrafts.imageGenerationForm ||
current.networkSafetyForm !== requestDrafts.networkSafetyForm ||
current.transcriptionForm !== requestDrafts.transcriptionForm || current.webSearchForm !== requestDrafts.webSearchForm,
});
setPendingRestartSections(EMPTY_PENDING_RESTART_SECTIONS);
setError(null);
} catch (err) {
setError((err as Error).message);
} finally {
setHostEngineApplying(false);
}
return;
}
onRestart?.();
}, [applyPayload, onNativeEngineRestart, onRestart, settings]);
const maybeRestartHostEngine = useCallback(
async (payload: RestartAwarePayload) => {
const surface = payload.surface ?? payload.runtime_surface ?? settings?.surface ?? settings?.runtime_surface;
const capabilities = payload.runtime_capabilities ?? settings?.runtime_capabilities;
const isNativeHost = surface === "native";
if (
!payload.requires_restart ||
!isNativeHost ||
!capabilities?.can_restart_engine ||
!onNativeEngineRestart
) {
return;
}
setHostEngineApplying(true);
try {
const nextToken = await onNativeEngineRestart();
const refreshed = await fetchSettings(nextToken);
applyPayload(refreshed, { preserveAgentForm: true, preserveCapabilityForms: true });
setPendingRestartSections(EMPTY_PENDING_RESTART_SECTIONS);
setError(null);
} catch (err) {
setError((err as Error).message);
} finally {
setHostEngineApplying(false);
}
},
[applyPayload, onNativeEngineRestart, settings],
);
const systemActions = createSystemSettingsActions({
state: systemState,
featureCatalog,
client,
token,
getToken,
t,
applyPayload,
maybeRestartHostEngine,
setPendingRestartSections,
refreshAutomations,
});
const { installCapabilities } = systemActions;
const modelActions = useModelSettingsActions({
state: modelState,
settings,
client,
t,
applyPayload,
maybeRestartHostEngine,
setPendingRestartSections,
setError,
onModelNameChange,
remoteBrowserAccess,
closeProviderOAuthFlow,
installCapabilities,
configuredModelProviderOptions,
});
const capabilityActions = useCapabilitySettingsActions({
state: capabilityState,
settings,
client,
t,
applyPayload,
maybeRestartHostEngine,
setPendingRestartSections,
installCapabilities,
});
const modelEdits = useEditCompletion(form, modelDirty, modelActions.saveModelSettings,
!modelState.modelPresetCreating && !!form.model.trim(), modelActions.modelEditIdentity);
const safetyEdits = useEditCompletion(networkSafetyForm, networkSafetyDirty, capabilityActions.saveNetworkSafetySettings);
const imageEdits = useEditCompletion(imageGenerationForm, imageGenerationDirty, capabilityActions.saveImageGenerationSettings,
!imageGenerationForm.enabled || Boolean(settings?.image_generation.providers.find(
(provider) => provider.name === imageGenerationForm.provider,
)?.configured));
const transcriptionEdits = useEditCompletion(transcriptionForm, transcriptionDirty, capabilityActions.saveTranscriptionSettings);
const webDraft = settings ? webSearchDraftState(settings, webSearchForm) : null;
const webEdits = useEditCompletion(webSearchForm, webDraft?.dirty ?? false, capabilityActions.saveWebSearch,
!webDraft?.missingCredential && (webSearchForm.provider !== "olostep" ||
featureCatalog.some((feature) => feature.name === "olostep" && feature.installed)));
return {
modelState,
modelActions,
capabilityState,
capabilityActions,
modelEdits,
safetyEdits,
imageEdits,
transcriptionEdits,
webEdits,
systemState,
systemActions,
activeSection,
runtimeConfigState,
closeProviderOAuthFlow,
error,
featureCatalog,
hostEngineApplying,
imageGenerationDirty,
loading,
localPrefs,
modelDirty,
networkSafetyDirty,
pendingRestartSections,
remoteBrowserAccess,
restartViaSettingsSurface,
selectSection,
setLocalPrefs,
settings,
t,
token,
transcriptionDirty,
};
}
export type SettingsController = ReturnType<typeof useSettingsController>;