feat: add assistant board styling tools

This commit is contained in:
ajnart committed 2026-08-01 10:39:41 +02:00
1 parent a5fa6d3afe
commit 5458e7d647
21 files changed
+811 -18

No files matched your search

+12
View File
@@ -133,6 +133,18 @@ App creation uses Homarr's native app form inside the conversation. The form reu
including automatic matching and searches through the `icon.findIcons` procedure, before the final
`app.create` approval is requested. The model is instructed not to invent external icon CDN URLs.
Board appearance changes use a similar review flow. The assistant first reads the board's current settings,
including its complete custom stylesheet, and then opens an editable form with Custom CSS, Appearance,
Background, and General tabs. The form highlights how many fields were proposed, preserves settings the
assistant did not change, and returns only values that differ from the current board. Custom CSS can be
copied or restored before continuing, and Homarr warns when it contains an imported stylesheet or remote
resource URL. Continuing from the form opens the normal mutation approval before anything is saved.
Ask for changes such as “make the cards denser on my Home board,” “add a mobile CSS rule without removing
my existing styles,” or “change the board colors and disable app status checks.” The current user must have
modify permission on the selected board. The empty conversation includes an **Improve a dashboard** starter,
and `/style` prepares the same guided workflow from the composer.
Homarr also exposes a small set of browser-only actions to the assistant. These actions can navigate to
safe internal routes and open Homarr interfaces such as the command menu and media request search.
They never receive provider credentials and cannot navigate to arbitrary external URLs.
+5 -1
View File
@@ -142,6 +142,10 @@ Change the radius of your items / categories.
This is the field where you can enter custom CSS.
The styling will only be applied on the respective board page.
When Homarr Assistant is enabled, users with modify permission can also ask it to edit the board's Custom
CSS and other visual or behavior settings. The assistant reads the current stylesheet first and presents an
editable review form before requesting approval to save the change.
[See this guide on how to work with custom CSS](/docs/advanced/styling/).
### Behaviour
@@ -255,4 +259,4 @@ For the global home board you can only select boards that are public.
### Mobile home board
Same as the home board, you can also set a mobile home board.
It will be used for devices that are detected as mobile devices. (Using User-Agent header)
It will be used for devices that are detected as mobile devices. (Using User-Agent header)
+1 -1
View File
@@ -129,7 +129,7 @@ Homarr exposes 50+ tools organized by namespace. Each tool is either a **query**
| `app` | List all apps, get app by ID, create/update/delete app | GET + POST |
| `apiKeys` | List API keys | GET |
| `beszel` | Systems status, alerts, historical system metrics | GET |
| `board` | List boards, get board by ID, create/update/delete board | GET + POST |
| `board` | List boards, read settings/CSS, create/update/delete board | GET + POST |
| `docker` | List containers, inspect container, start/stop/restart | GET + POST |
| `icon` | Search icons | GET |
| `info` | Server health, version info | GET |
@@ -57,6 +57,36 @@ describe("getForcedAssistantToolName", () => {
).toBeUndefined();
});
test("continues directly from reviewed board settings to the settings mutation", () => {
expect(
getForcedAssistantToolName([
assistantMessage({
type: "dynamic-tool",
toolName: "configure_board_settings",
toolCallId: "settings-1",
input: { boardId: "board-1", boardName: "Home", changes: { customCss: ".item {}" } },
state: "output-available",
output: { id: "board-1", customCss: ".item {}" },
}),
]),
).toBe("board_savePartialBoardSettings");
});
test("does not request a mutation when board settings were left unchanged", () => {
expect(
getForcedAssistantToolName([
assistantMessage({
type: "dynamic-tool",
toolName: "configure_board_settings",
toolCallId: "settings-1",
input: { boardId: "board-1", boardName: "Home", changes: {} },
state: "output-available",
output: { id: "board-1", cancelled: true },
}),
]),
).toBeUndefined();
});
test("does not repeat app creation after the mutation tool has been called", () => {
expect(
getForcedAssistantToolName([
@@ -14,13 +14,23 @@ export const getForcedAssistantToolName = (messages: UIMessage[]) => {
if (latestMessage?.role !== "assistant") return undefined;
const latestToolPart = latestMessage.parts.toReversed().find((part) => isToolUIPart(part));
if (latestToolPart === undefined || latestToolPart.state !== "output-available") return undefined;
const nextToolByHumanTool = {
configure_app: "app_create",
configure_board_settings: "board_savePartialBoardSettings",
} as const;
const toolName = getToolName(latestToolPart);
if (
latestToolPart === undefined ||
getToolName(latestToolPart) !== "configure_app" ||
latestToolPart.state !== "output-available"
toolName === "configure_board_settings" &&
typeof latestToolPart.output === "object" &&
latestToolPart.output !== null &&
"cancelled" in latestToolPart.output &&
latestToolPart.output.cancelled === true
) {
return undefined;
}
return "app_create" as const;
return toolName in nextToolByHumanTool
? nextToolByHumanTool[toolName as keyof typeof nextToolByHumanTool]
: undefined;
};
@@ -94,6 +94,7 @@ Action rules:
- A prose response such as "Please confirm if you would like me to proceed", "Would you like me to proceed?", or a parameter summary that asks for confirmation is incorrect. Never ask for a second textual confirmation before an approval-gated tool call.
- Do not retry a denied action.
- Before creating an app, call configure_app with the best defaults so the user can review Homarr's native app form. Its icon picker searches Homarr's local icon repository. Use the returned values for app_create.
- Before changing a board's custom CSS or visual and behavior settings, call board_getBoardSettings to read the current values, then call configure_board_settings with only the requested proposed changes. The user can edit the complete CSS and settings in Homarr's native form. Use its returned flat object for board_savePartialBoardSettings, which then shows the mutation approval. Never overwrite existing CSS rules unless the user explicitly requests replacement.
- When choosing an app icon without configure_app, call the Homarr icon findIcons tool first and use one of its returned local icon URLs. Never invent a third-party icon CDN URL.
- Browser tools can navigate within Homarr or open existing Homarr UI. Never navigate to an arbitrary external URL.
- Keep responses concise and lead with the result. Summarize tool output instead of dumping JSON.
@@ -0,0 +1,401 @@
"use client";
import { useMemo, useState } from "react";
import type { ToolCallMessagePartProps } from "@assistant-ui/react";
import {
Alert,
Badge,
Box,
Button,
ColorInput,
CopyButton,
Group,
InputWrapper,
Select,
SimpleGrid,
Skeleton,
Slider,
Stack,
Switch,
Tabs,
Text,
Textarea,
TextInput,
ThemeIcon,
Tooltip,
} from "@mantine/core";
import {
IconAlertTriangle,
IconCheck,
IconCopy,
IconFileTypeCss,
IconPalette,
IconPhoto,
IconRefresh,
IconSettings,
} from "@tabler/icons-react";
import type { z } from "zod/v4";
import type { RouterOutputs } from "@homarr/api";
import { clientApi } from "@homarr/api/client";
import { backgroundImageAttachments, backgroundImageRepeats, backgroundImageSizes } from "@homarr/definitions";
import { useZodForm } from "@homarr/form";
import { useI18n, useScopedI18n } from "@homarr/translation/client";
import { boardSavePartialSettingsSchema } from "@homarr/validation/board";
import { getChangedBoardSettings, getCustomCssWarnings } from "./assistant-board-settings";
import classes from "./assistant-panel.module.css";
import type {
AssistantBoardSettingsChanges,
ConfigureBoardSettingsArgs,
ConfigureBoardSettingsResult,
} from "./assistant-tool-contracts";
type BoardSettings = RouterOutputs["board"]["getBoardSettings"];
const completeSettingsSchema = boardSavePartialSettingsSchema.required();
type BoardSettingsFormValues = z.infer<typeof completeSettingsSchema>;
const normalizeFormValues = (
current: BoardSettings,
proposed: AssistantBoardSettingsChanges,
): BoardSettingsFormValues => {
const values = { ...current, ...proposed };
return {
pageTitle: values.pageTitle ?? "",
metaTitle: values.metaTitle ?? "",
logoImageUrl: values.logoImageUrl ?? "",
faviconImageUrl: values.faviconImageUrl ?? "",
backgroundImageUrl: values.backgroundImageUrl ?? "",
backgroundImageAttachment: values.backgroundImageAttachment,
backgroundImageRepeat: values.backgroundImageRepeat,
backgroundImageSize: values.backgroundImageSize,
primaryColor: values.primaryColor,
secondaryColor: values.secondaryColor,
opacity: values.opacity,
customCss: values.customCss,
iconColor: values.iconColor ?? "",
itemRadius: values.itemRadius,
disableStatus: values.disableStatus,
};
};
const toCurrentValues = (current: BoardSettings): BoardSettingsFormValues => normalizeFormValues(current, {});
export const AssistantConfigureBoardSettingsTool = ({
args,
result,
addResult,
}: ToolCallMessagePartProps<ConfigureBoardSettingsArgs, ConfigureBoardSettingsResult>) => {
const t = useScopedI18n("common.assistant.configureBoardSettings");
const boardId = args?.boardId ?? "";
const settings = clientApi.board.getBoardSettings.useQuery(
{ id: boardId },
{ enabled: result === undefined && boardId.length > 0, retry: false },
);
if (result) {
const cancelled = "cancelled" in result && result.cancelled;
const changedCount = cancelled ? 0 : Math.max(0, Object.keys(result).length - 1);
return (
<Box className={classes.humanToolCompleted}>
<ThemeIcon size="sm" radius="xl" variant="light" color="green">
<IconCheck size={13} />
</ThemeIcon>
<Box miw={0}>
<Text size="xs" c="dimmed">
{cancelled ? t("cancelled") : t("ready")}
</Text>
<Text size="sm" fw={600} truncate>
{cancelled ? args?.boardName : t("changeCount", { count: changedCount })}
</Text>
</Box>
</Box>
);
}
if (!args?.boardId || !args.boardName) {
return <BoardSettingsSkeleton label={t("loading")} />;
}
if (settings.isError) {
return (
<Alert color="red" variant="light" title={t("loadErrorTitle")} icon={<IconAlertTriangle size={18} />}>
<Stack gap="sm">
<Text size="sm">{t("loadErrorDescription")}</Text>
<Button variant="light" color="red" size="compact-sm" w="fit-content" onClick={() => settings.refetch()}>
{t("retry")}
</Button>
</Stack>
</Alert>
);
}
if (!settings.data) return <BoardSettingsSkeleton label={t("loading")} />;
return (
<BoardSettingsForm
current={settings.data}
args={args}
onSubmit={(changes) => addResult({ id: settings.data.id, ...changes })}
onCancel={() => addResult({ id: settings.data.id, cancelled: true })}
/>
);
};
const BoardSettingsSkeleton = ({ label }: { label: string }) => (
<Box className={classes.boardSettingsTool} aria-label={label}>
<Stack gap="sm">
<Skeleton height={20} width="45%" />
<Skeleton height={14} width="78%" />
<Skeleton height={38} />
<Skeleton height={180} />
</Stack>
</Box>
);
const BoardSettingsForm = ({
current,
args,
onSubmit,
onCancel,
}: {
current: BoardSettings;
args: ConfigureBoardSettingsArgs;
onSubmit: (changes: AssistantBoardSettingsChanges) => void;
onCancel: () => void;
}) => {
const t = useScopedI18n("common.assistant.configureBoardSettings");
const boardT = useI18n();
const [submitting, setSubmitting] = useState(false);
const currentValues = useMemo(() => toCurrentValues(current), [current]);
const form = useZodForm(completeSettingsSchema, {
initialValues: normalizeFormValues(current, args.changes),
});
const changes = getChangedBoardSettings(currentValues, form.values);
const changedCount = Object.keys(changes).length;
const cssWarnings = getCustomCssWarnings(form.values.customCss);
const proposedKeys = Object.keys(args.changes);
const defaultTab =
args.changes.customCss !== undefined ? "css" : proposedKeys.some(isAppearanceKey) ? "appearance" : "general";
const optionData = <TValue extends string>(
values: readonly TValue[],
key: "backgroundImageAttachment" | "backgroundImageRepeat" | "backgroundImageSize",
) =>
values.map((value) => ({
value,
label: boardT(`board.field.${key}.option.${value}.label` as never),
}));
return (
<Box className={classes.boardSettingsTool}>
<Group className={classes.boardSettingsHeader} align="flex-start" wrap="nowrap" gap="sm">
<ThemeIcon size="lg" radius="xl" variant="light" color="red">
<IconSettings size={18} />
</ThemeIcon>
<Box flex={1} miw={0}>
<Group gap="xs" wrap="wrap">
<Text fw={700}>{t("title")}</Text>
<Badge variant="light" color="gray" size="sm">
{args.boardName}
</Badge>
</Group>
<Text size="sm" c="dimmed" mt={3}>
{args.summary}
</Text>
{proposedKeys.length > 0 && (
<Text size="xs" c="dimmed" mt="xs">
{t("proposedCount", { count: proposedKeys.length })}
</Text>
)}
</Box>
</Group>
<form
onSubmit={form.onSubmit((values) => {
if (submitting) return;
const nextChanges = getChangedBoardSettings(currentValues, values);
setSubmitting(true);
if (Object.keys(nextChanges).length === 0) {
onCancel();
return;
}
onSubmit(nextChanges);
})}
>
<Tabs defaultValue={defaultTab} mt="md" className={classes.boardSettingsTabs}>
<Tabs.List grow>
<Tabs.Tab value="css" leftSection={<IconFileTypeCss size={15} />}>
{t("tabs.css")}
</Tabs.Tab>
<Tabs.Tab value="appearance" leftSection={<IconPalette size={15} />}>
{t("tabs.appearance")}
</Tabs.Tab>
<Tabs.Tab value="background" leftSection={<IconPhoto size={15} />}>
{t("tabs.background")}
</Tabs.Tab>
<Tabs.Tab value="general" leftSection={<IconSettings size={15} />}>
{t("tabs.general")}
</Tabs.Tab>
</Tabs.List>
<Tabs.Panel value="css" pt="md">
<Stack gap="sm">
<Textarea
label={boardT("board.field.customCss.label")}
description={t("cssDescription")}
autosize
minRows={10}
maxRows={20}
classNames={{ input: classes.boardCssEditor }}
{...form.getInputProps("customCss")}
/>
<Group justify="space-between" gap="xs" wrap="wrap">
<Text size="xs" c={form.values.customCss.length > 15_500 ? "orange" : "dimmed"}>
{t("cssCharacters", { count: form.values.customCss.length })}
</Text>
<Group gap="xs">
<CopyButton value={form.values.customCss}>
{({ copied, copy }) => (
<Tooltip label={copied ? t("copied") : t("copyCss")}>
<Button
variant="subtle"
size="compact-sm"
leftSection={copied ? <IconCheck size={14} /> : <IconCopy size={14} />}
onClick={copy}
>
{copied ? t("copied") : t("copy")}
</Button>
</Tooltip>
)}
</CopyButton>
<Button
variant="subtle"
color="gray"
size="compact-sm"
leftSection={<IconRefresh size={14} />}
disabled={form.values.customCss === currentValues.customCss}
onClick={() => form.setFieldValue("customCss", currentValues.customCss)}
>
{t("restoreCss")}
</Button>
</Group>
</Group>
{(cssWarnings.importsStylesheet || cssWarnings.loadsRemoteResource) && (
<Alert
variant="light"
color="yellow"
icon={<IconAlertTriangle size={18} />}
title={t("remoteCssTitle")}
>
{t("remoteCssDescription")}
</Alert>
)}
</Stack>
</Tabs.Panel>
<Tabs.Panel value="appearance" pt="md">
<Stack gap="md">
<SimpleGrid cols={{ base: 1, sm: 2 }}>
<ColorInput
label={boardT("board.field.primaryColor.label")}
format="hex"
{...form.getInputProps("primaryColor")}
/>
<ColorInput
label={boardT("board.field.secondaryColor.label")}
format="hex"
{...form.getInputProps("secondaryColor")}
/>
<ColorInput
label={boardT("board.field.iconColor.label")}
format="hex"
{...form.getInputProps("iconColor")}
/>
<Select
label={boardT("board.field.itemRadius.label")}
data={(["xs", "sm", "md", "lg", "xl"] as const).map((value) => ({
value,
label: boardT(`board.field.itemRadius.option.${value}`),
}))}
{...form.getInputProps("itemRadius")}
/>
</SimpleGrid>
<InputWrapper label={boardT("board.field.opacity.label")}>
<Slider min={0} max={100} step={5} label={(value) => `${value}%`} {...form.getInputProps("opacity")} />
</InputWrapper>
</Stack>
</Tabs.Panel>
<Tabs.Panel value="background" pt="md">
<Stack gap="md">
<TextInput
label={boardT("board.field.backgroundImageUrl.label")}
placeholder={boardT("board.field.backgroundImageUrl.placeholder")}
{...form.getInputProps("backgroundImageUrl")}
/>
<SimpleGrid cols={{ base: 1, sm: 2 }}>
<Select
label={boardT("board.field.backgroundImageSize.label")}
data={optionData(backgroundImageSizes.values, "backgroundImageSize")}
{...form.getInputProps("backgroundImageSize")}
/>
<Select
label={boardT("board.field.backgroundImageRepeat.label")}
data={optionData(backgroundImageRepeats.values, "backgroundImageRepeat")}
{...form.getInputProps("backgroundImageRepeat")}
/>
<Select
label={boardT("board.field.backgroundImageAttachment.label")}
data={optionData(backgroundImageAttachments.values, "backgroundImageAttachment")}
{...form.getInputProps("backgroundImageAttachment")}
/>
</SimpleGrid>
</Stack>
</Tabs.Panel>
<Tabs.Panel value="general" pt="md">
<Stack gap="md">
<SimpleGrid cols={{ base: 1, sm: 2 }}>
<TextInput label={boardT("board.field.pageTitle.label")} {...form.getInputProps("pageTitle")} />
<TextInput label={boardT("board.field.metaTitle.label")} {...form.getInputProps("metaTitle")} />
<TextInput label={boardT("board.field.logoImageUrl.label")} {...form.getInputProps("logoImageUrl")} />
<TextInput
label={boardT("board.field.faviconImageUrl.label")}
{...form.getInputProps("faviconImageUrl")}
/>
</SimpleGrid>
<Switch
label={boardT("board.field.disableStatus.label")}
description={boardT("board.field.disableStatus.description")}
{...form.getInputProps("disableStatus", { type: "checkbox" })}
/>
</Stack>
</Tabs.Panel>
</Tabs>
<Group className={classes.boardSettingsActions} justify="space-between" gap="sm" mt="md" wrap="wrap">
<Button
variant="subtle"
color="gray"
leftSection={<IconRefresh size={15} />}
disabled={changedCount === 0 || submitting}
onClick={() => form.setValues(currentValues)}
>
{t("resetAll")}
</Button>
<Group gap="sm" wrap="nowrap" className={classes.boardSettingsSubmitGroup}>
<Text size="xs" c="dimmed">
{changedCount === 0 ? t("noChanges") : t("changeCount", { count: changedCount })}
</Text>
<Button type="submit" loading={submitting}>
{changedCount === 0 ? t("keepCurrent") : t("continue")}
</Button>
</Group>
</Group>
</form>
</Box>
);
};
const isAppearanceKey = (key: string) =>
["primaryColor", "secondaryColor", "opacity", "iconColor", "itemRadius"].includes(key);
@@ -0,0 +1,29 @@
import { describe, expect, test } from "vitest";
import { getChangedBoardSettings, getCustomCssWarnings } from "./assistant-board-settings";
describe("getChangedBoardSettings", () => {
test("returns only changed settings and treats empty nullable values equally", () => {
expect(
getChangedBoardSettings(
{ pageTitle: null, primaryColor: "#112233", opacity: 85 },
{ pageTitle: "", primaryColor: "#445566", opacity: 85 },
),
).toEqual({ primaryColor: "#445566" });
});
test("keeps an intentional custom CSS removal", () => {
expect(getChangedBoardSettings({ customCss: ".item { color: red; }" }, { customCss: "" })).toEqual({
customCss: "",
});
});
});
describe("getCustomCssWarnings", () => {
test("detects imported and remote CSS resources", () => {
expect(getCustomCssWarnings('@import "theme.css"; .item { background: url(https://example.com/a.png); }')).toEqual({
importsStylesheet: true,
loadsRemoteResource: true,
});
});
});
@@ -0,0 +1,33 @@
import type { AssistantBoardSettingsChanges } from "./assistant-tool-contracts";
export const assistantBoardSettingKeys = [
"pageTitle",
"metaTitle",
"logoImageUrl",
"faviconImageUrl",
"backgroundImageUrl",
"backgroundImageAttachment",
"backgroundImageRepeat",
"backgroundImageSize",
"primaryColor",
"secondaryColor",
"opacity",
"customCss",
"iconColor",
"itemRadius",
"disableStatus",
] as const satisfies readonly (keyof AssistantBoardSettingsChanges)[];
const comparableValue = (value: unknown) => (value === null ? "" : value);
export const getChangedBoardSettings = (current: AssistantBoardSettingsChanges, next: AssistantBoardSettingsChanges) =>
Object.fromEntries(
assistantBoardSettingKeys.flatMap((key) =>
comparableValue(current[key]) === comparableValue(next[key]) ? [] : [[key, next[key]]],
),
) as AssistantBoardSettingsChanges;
export const getCustomCssWarnings = (css: string) => ({
importsStylesheet: /@import\b/iu.test(css),
loadsRemoteResource: /url\(\s*["']?https?:\/\//iu.test(css),
});
@@ -55,6 +55,43 @@
height: 2.5rem;
}
.boardSettingsTool {
padding: 0.9rem;
border: 1px solid var(--mantine-color-default-border);
border-radius: var(--mantine-radius-md);
background: var(--mantine-color-body);
}
.boardSettingsHeader {
min-width: 0;
}
.boardSettingsTabs :global(.mantine-Tabs-list) {
flex-wrap: nowrap;
overflow-x: auto;
scrollbar-width: thin;
}
.boardSettingsTabs :global(.mantine-Tabs-tab) {
min-width: max-content;
}
.boardCssEditor {
line-height: 1.55;
tab-size: 2;
font-family: var(--mantine-font-family-monospace);
font-size: var(--mantine-font-size-xs);
}
.boardSettingsActions {
padding-top: 0.8rem;
border-top: 1px solid var(--mantine-color-default-border);
}
.boardSettingsSubmitGroup {
margin-inline-start: auto;
}
.floatingPanel {
position: fixed;
z-index: 290;
@@ -1049,9 +1086,20 @@
}
.humanTool,
.appTool {
.appTool,
.boardSettingsTool {
padding: 0.8rem;
}
.boardSettingsActions,
.boardSettingsSubmitGroup {
width: 100%;
}
.boardSettingsSubmitGroup {
justify-content: space-between;
margin-inline-start: 0;
}
}
@media (prefers-reduced-motion: reduce) {
@@ -68,13 +68,13 @@ import {
IconChevronUp,
IconCopy,
IconDownload,
IconCommand,
IconFile,
IconFileExport,
IconLink,
IconMessage,
IconMinus,
IconPaperclip,
IconPalette,
IconPencil,
IconHistory,
IconPlayerStop,
@@ -1061,9 +1061,9 @@ const EmptyThread = () => {
{t("suggestions.media.label")}
</Button>
</ThreadPrimitive.Suggestion>
<ThreadPrimitive.Suggestion prompt={t("suggestions.command.prompt")} send asChild>
<Button variant="default" className={classes.suggestion} leftSection={<IconCommand size={18} />}>
{t("suggestions.command.label")}
<ThreadPrimitive.Suggestion prompt={t("suggestions.style.prompt")} send asChild>
<Button variant="default" className={classes.suggestion} leftSection={<IconPalette size={18} />}>
{t("suggestions.style.label")}
</Button>
</ThreadPrimitive.Suggestion>
</Box>
@@ -1189,6 +1189,12 @@ const ComposerTriggers = () => {
description: t("commands.media"),
execute: () => aui.composer().setText(t("suggestions.media.prompt")),
},
{
id: "style",
label: "/style",
description: t("commands.style"),
execute: () => aui.composer().setText(t("suggestions.style.prompt")),
},
],
});
@@ -1471,7 +1477,11 @@ const usePendingActionCopy = (action: AssistantPendingAction | undefined) => {
return { title: t("pendingAction.answerTitle"), detail: action.detail ?? t("pendingAction.answerFallback") };
}
if (action.kind === "form") {
return { title: t("pendingAction.formTitle"), detail: action.detail ?? t("configureApp.title") };
const isBoardSettings = action.toolName === "configure_board_settings";
return {
title: isBoardSettings ? t("pendingAction.boardFormTitle") : t("pendingAction.formTitle"),
detail: action.detail ?? (isBoardSettings ? t("configureBoardSettings.title") : t("configureApp.title")),
};
}
const tool = action.toolName.replaceAll("_", " ");
return { title: t("activity.approval"), detail: action.detail ? `${tool} · ${action.detail}` : tool };
@@ -61,6 +61,20 @@ describe("getPendingAssistantAction", () => {
).toEqual({ kind: "form", toolName: "configure_app", detail: "Wikipedia" });
});
test("exposes the board settings form while changes still need review", () => {
expect(
getPendingAssistantAction(
assistantMessage({
type: "tool-call",
toolCallId: "settings-1",
toolName: "configure_board_settings",
args: { boardId: "board-1", boardName: "Home", changes: { customCss: ".item {}" } },
argsText: "{}",
}),
),
).toEqual({ kind: "form", toolName: "configure_board_settings", detail: "Home" });
});
test("exposes an unresolved mutation approval", () => {
expect(
getPendingAssistantAction(
@@ -9,6 +9,7 @@ export type AssistantPendingAction = {
const humanToolKinds = {
ask_user: "question",
configure_app: "form",
configure_board_settings: "form",
} as const;
const getStringArg = (args: unknown, key: string) => {
@@ -37,7 +38,10 @@ export const getPendingAssistantAction = (message: ThreadMessage | undefined): A
return {
kind,
toolName: part.toolName,
detail: getStringArg(part.args, kind === "question" ? "question" : "name"),
detail: getStringArg(
part.args,
kind === "question" ? "question" : part.toolName === "configure_board_settings" ? "boardName" : "name",
),
};
}
@@ -33,6 +33,7 @@ import { AssistantRuntimeProviderWithTools } from "./assistant-runtime-provider"
import { sendAssistantPrompt as sendPromptThroughComposer } from "./assistant-send";
import { createAssistantPromptInteraction } from "./assistant-spotlight";
import { browserToolContracts } from "./assistant-tool-contracts";
import { AssistantConfigureBoardSettingsTool } from "./assistant-board-settings-tool";
import type { AssistantUIMessage } from "./assistant-message-metadata";
interface AssistantContextValue {
@@ -412,6 +413,12 @@ const AssistantRuntime = ({ children }: PropsWithChildren) => {
...browserToolContracts.configure_app,
render: AssistantConfigureAppTool,
},
configure_board_settings: {
type: "human",
display: "standalone",
...browserToolContracts.configure_board_settings,
render: AssistantConfigureBoardSettingsTool,
},
navigate_to_route: {
type: "frontend",
...browserToolContracts.navigate_to_route,
@@ -1,4 +1,5 @@
import { describe, expect, test } from "vitest";
import { z } from "zod/v4";
import { browserToolContracts, normalizeAssistantAppIconUrl } from "./assistant-tool-contracts";
@@ -34,6 +35,35 @@ describe("assistant human tool contracts", () => {
).toBe(true);
});
test("accepts a scoped board settings proposal", () => {
expect(
browserToolContracts.configure_board_settings.parameters.safeParse({
boardId: "board-1",
boardName: "Home",
summary: "Improve dashboard contrast and tighten card spacing.",
changes: {
primaryColor: "#7C3AED",
customCss: ".mantine-Card-root { padding: 0.75rem; }",
},
}).success,
).toBe(true);
});
test("rejects invalid board colors and oversized CSS", () => {
expect(
browserToolContracts.configure_board_settings.parameters.safeParse({
boardId: "board-1",
boardName: "Home",
summary: "Change styling",
changes: { primaryColor: "purple", customCss: "a".repeat(16_385) },
}).success,
).toBe(false);
});
test("converts the board review parameters to a provider JSON schema", () => {
expect(() => z.toJSONSchema(browserToolContracts.configure_board_settings.parameters)).not.toThrow();
});
test("only preserves usable app icon URLs", () => {
expect(normalizeAssistantAppIconUrl("youtube")).toBe("");
expect(normalizeAssistantAppIconUrl("/api/media/youtube.svg")).toBe("/api/media/youtube.svg");
@@ -1,11 +1,43 @@
import { z } from "zod/v4";
import { backgroundImageAttachments, backgroundImageRepeats, backgroundImageSizes } from "@homarr/definitions";
const askUserOptionSchema = z.object({
id: z.string().trim().min(1).max(48),
label: z.string().trim().min(1).max(80),
description: z.string().trim().max(180).optional(),
});
const boardImageValueSchema = z.string().trim().max(2_048).nullable();
const boardTitleValueSchema = z.string().trim().max(255).nullable();
const boardColorSchema = z.string().regex(/^#[0-9A-Fa-f]{6}$/);
export const assistantBoardSettingsChangesSchema = z
.object({
pageTitle: boardTitleValueSchema.optional(),
metaTitle: boardTitleValueSchema.optional(),
logoImageUrl: boardImageValueSchema.optional(),
faviconImageUrl: boardImageValueSchema.optional(),
backgroundImageUrl: boardImageValueSchema.optional(),
backgroundImageAttachment: z.enum(backgroundImageAttachments.values).optional(),
backgroundImageRepeat: z.enum(backgroundImageRepeats.values).optional(),
backgroundImageSize: z.enum(backgroundImageSizes.values).optional(),
primaryColor: boardColorSchema.optional(),
secondaryColor: boardColorSchema.optional(),
opacity: z.number().min(0).max(100).optional(),
customCss: z
.string()
.max(16_384)
.optional()
.describe(
"The complete resulting board stylesheet. Preserve existing rules from board_getBoardSettings unless the user explicitly asks to replace them.",
),
iconColor: boardColorSchema.nullable().optional(),
itemRadius: z.enum(["xs", "sm", "md", "lg", "xl"]).optional(),
disableStatus: z.boolean().optional(),
})
.describe("Only the board fields the user asked to change.");
export const browserToolContracts = {
ask_user: {
description:
@@ -35,6 +67,16 @@ export const browserToolContracts = {
pingUrl: z.string().trim().max(2_048).nullable().optional(),
}),
},
configure_board_settings: {
description:
"Open Homarr's native board settings and custom CSS review form. Always call board_getBoardSettings first, then pass only the requested proposed changes here. The user can edit the complete stylesheet and all supported settings. Use the returned flat object directly with board_savePartialBoardSettings; do not ask for confirmation in prose.",
parameters: z.object({
boardId: z.string().trim().min(1).max(64),
boardName: z.string().trim().min(1).max(255),
summary: z.string().trim().min(1).max(400),
changes: assistantBoardSettingsChangesSchema,
}),
},
navigate_to_route: {
description:
"Navigate the current Homarr tab to a safe internal route. Only same-origin paths beginning with a single slash are accepted.",
@@ -59,6 +101,13 @@ export type AskUserResult = {
source: "option" | "other";
};
export type ConfigureAppArgs = z.infer<(typeof browserToolContracts)["configure_app"]["parameters"]>;
export type ConfigureBoardSettingsArgs = z.infer<
(typeof browserToolContracts)["configure_board_settings"]["parameters"]
>;
export type AssistantBoardSettingsChanges = z.infer<typeof assistantBoardSettingsChangesSchema>;
export type ConfigureBoardSettingsResult =
| (AssistantBoardSettingsChanges & { id: string })
| { id: string; cancelled: true };
export const normalizeAssistantAppIconUrl = (value: string | undefined) => {
if (!value) return "";
+52
View File
@@ -52,6 +52,7 @@ import {
boardSavePartialSettingsSchema,
boardSavePermissionsSchema,
boardSaveSchema,
boardSettingsSchema,
boardSummarySchema,
} from "@homarr/validation/board";
import { byIdSchema } from "@homarr/validation/common";
@@ -682,6 +683,57 @@ export const boardRouter = createTRPCRouter({
return await getFullBoardWithWhereAsync(ctx.db, boardWhere, ctx.session?.user.id ?? null);
}),
getBoardSettings: protectedProcedure
.meta({
mcp: {
enabled: true,
description:
"Read the editable visual and behavior settings for one board, including its current custom CSS. Requires modify permission. REQUIRED: id (board ID). Call this before proposing board settings or custom CSS changes",
},
})
.input(z.object({ id: z.string() }))
.output(boardSettingsSchema)
.query(async ({ input, ctx }) => {
const boardWhere = eq(boards.id, input.id);
await throwIfActionForbiddenAsync(ctx, boardWhere, "modify");
const board = await ctx.db.query.boards.findFirst({
columns: {
id: true,
name: true,
pageTitle: true,
metaTitle: true,
logoImageUrl: true,
faviconImageUrl: true,
backgroundImageUrl: true,
backgroundImageAttachment: true,
backgroundImageRepeat: true,
backgroundImageSize: true,
primaryColor: true,
secondaryColor: true,
opacity: true,
customCss: true,
iconColor: true,
itemRadius: true,
disableStatus: true,
},
where: boardWhere,
});
if (!board) {
throw new TRPCError({ code: "NOT_FOUND", message: "Board not found" });
}
return {
...board,
pageTitle: board.pageTitle ?? "",
metaTitle: board.metaTitle ?? "",
logoImageUrl: board.logoImageUrl ?? "",
faviconImageUrl: board.faviconImageUrl ?? "",
backgroundImageUrl: board.backgroundImageUrl ?? "",
customCss: board.customCss ?? "",
iconColor: board.iconColor ?? "",
};
}),
saveLayouts: protectedProcedure.input(boardSaveLayoutsSchema).mutation(async ({ ctx, input }) => {
await throwIfActionForbiddenAsync(ctx, eq(boards.id, input.id), "modify");
@@ -586,6 +586,28 @@ describe("getBoardByName should return board by name", () => {
});
});
describe("getBoardSettings should return editable board settings", () => {
test("returns current custom CSS and requires modify permission", async () => {
const spy = vi.spyOn(boardAccess, "throwIfActionForbiddenAsync");
const db = createDb();
const caller = boardRouter.createCaller({ db, deviceType: undefined, session: defaultSession });
const { boardId } = await createFullBoardAsync(db, "default");
const customCss = ".dashboard-card { border-radius: 0.5rem; }";
await db.update(boards).set({ customCss, primaryColor: "#123456", pageTitle: null }).where(eq(boards.id, boardId));
const result = await caller.getBoardSettings({ id: boardId });
expect(result).toMatchObject({
id: boardId,
name: "default",
customCss,
primaryColor: "#123456",
pageTitle: null,
});
expect(spy).toHaveBeenCalledWith(expect.anything(), expect.anything(), "modify");
});
});
describe("savePartialBoardSettings should save general settings", () => {
it("should save general settings", async () => {
// Arrange
+1
View File
@@ -54,6 +54,7 @@ test("MCP tools should contain expected procedures", () => {
expect(toolNames).toContain("app_byId");
expect(toolNames).toContain("app_create");
expect(toolNames).toContain("board_savePartialBoardSettings");
expect(toolNames).toContain("board_getBoardSettings");
expect(toolNames).toContain("board_duplicateBoard");
expect(toolNames).toContain("icon_findIcons");
expect(toolNames).toContain("info_getInfo");
+35 -4
View File
@@ -1543,9 +1543,9 @@
"label": "Find media to request",
"prompt": "Help me find a movie or series to request."
},
"command": {
"label": "Open the command menu",
"prompt": "Open the Homarr command menu for me."
"style": {
"label": "Improve a dashboard",
"prompt": "Help me improve a board's appearance or custom CSS. Show me my boards first, then preserve my current settings while we make the change."
}
},
"composerPlaceholder": "Ask Homarr Assistant…",
@@ -1601,7 +1601,8 @@
"hint": "Type / for shortcuts",
"health": "Prepare a service-health check",
"explore": "Prepare an overview of this Homarr instance",
"media": "Prepare a media search"
"media": "Prepare a media search",
"style": "Prepare a board appearance or custom CSS change"
},
"usage": {
"tokens": "tokens",
@@ -1641,6 +1642,7 @@
"answerTitle": "Answer needed",
"answerFallback": "Choose an answer to continue",
"formTitle": "Review app details",
"boardFormTitle": "Review board changes",
"review": "Review",
"sendBlocked": "Resolve the pending request before sending"
},
@@ -1670,6 +1672,35 @@
"continue": "Use these details",
"ready": "App details ready"
},
"configureBoardSettings": {
"title": "Review board changes",
"loading": "Loading current board settings",
"loadErrorTitle": "Board settings could not be loaded",
"loadErrorDescription": "The board may no longer exist, or you may not have permission to modify it.",
"retry": "Try again",
"proposedCount": "Assistant proposed {count} fields",
"changeCount": "{count} changes ready",
"ready": "Board changes ready",
"cancelled": "Current board settings kept",
"noChanges": "No settings will change",
"keepCurrent": "Keep current settings",
"continue": "Continue to approval",
"resetAll": "Reset all changes",
"tabs": {
"css": "Custom CSS",
"appearance": "Appearance",
"background": "Background",
"general": "General"
},
"cssDescription": "Edit the complete stylesheet. Existing rules are kept unless they are removed here.",
"cssCharacters": "{count} of 16384 characters",
"copy": "Copy",
"copyCss": "Copy CSS",
"copied": "Copied",
"restoreCss": "Restore current CSS",
"remoteCssTitle": "This CSS loads a remote resource",
"remoteCssDescription": "Imported stylesheets and remote URLs contact another server when the board loads. Review them before continuing."
},
"approvalRequired": "Approval required",
"complete": "Complete",
"denied": "Denied",
+5
View File
@@ -70,6 +70,11 @@ export const boardSavePartialSettingsSchema = z
})
.partial();
export const boardSettingsSchema = boardSavePartialSettingsSchema.required().extend({
id: z.string(),
name: z.string(),
});
export const boardSaveLayoutsSchema = z.object({
id: z.string(),
layouts: z.array(