feat(alerts): maintenance windows

apps/ai/src/mcp/dispatcher.ts

@@ -14,6 +14,7 @@ import { AlertIncidentAckService } from "@maple/backend/services/alerts/AlertInc
 import { AlertIncidentPagesService } from "@maple/backend/services/alerts/AlertIncidentPagesService"
 import { AlertRulesService } from "@maple/backend/services/alerts/AlertRulesService"
 import { EscalationChainsService } from "@maple/backend/services/alerts/EscalationChainsService"
+import { AlertMaintenanceWindowsService } from "@maple/backend/services/alerts/AlertMaintenanceWindowsService"
 import { OnCallSchedulesService } from "@maple/backend/services/alerts/OnCallSchedulesService"
 import { AlertSilencesService } from "@maple/backend/services/alerts/AlertSilencesService"
 
@@ -279,6 +280,7 @@ const McpRuntimeServicesLive = Layer.mergeAll(
 	AlertIncidentPagesService.layer,
 	AlertRulesService.layer,
 	EscalationChainsService.layer,
+	AlertMaintenanceWindowsService.layer,
 	OnCallSchedulesService.layer,
 	AlertSilencesService.layer,
 	AlertsService.layer,

apps/ai/src/mcp/lib/alert-silences.ts

@@ -92,6 +92,9 @@ export const createSilenceErrors = {
 export const endSilenceErrors = {
 	"@maple/http/errors/AlertSilenceNotFoundError": (error: AlertSilenceNotFoundError) =>
 		Effect.fail(silenceNotFound(error.silenceId)),
+	// A maintenance window's silence is ended through the window.
+	"@maple/http/errors/AlertValidationError": (error: AlertValidationError) =>
+		Effect.fail(new McpInvalidInputError({ message: error.message, parameter: "silence_id" })),
 	"@maple/http/errors/AlertForbiddenError": failWith("end_alert_silence"),
 	"@maple/http/errors/AlertPersistenceError": failWith("end_alert_silence"),
 }

apps/ai/src/mcp/lib/maintenance-windows.ts

@@ -0,0 +1,133 @@
+import { Array as Arr, Effect } from "effect"
+import type {
+	AlertForbiddenError,
+	AlertMaintenanceWindowDocument,
+	AlertMaintenanceWindowNotFoundError,
+	AlertPersistenceError,
+	AlertValidationError,
+} from "@maple/domain/http"
+import type { MaintenanceWindowRow } from "@maple/domain/mcp-outputs"
+import { McpInvalidInputError } from "../tools/types"
+import { toMcpHttpError } from "./map-http-error"
+import { doc } from "./tool-doc"
+
+type WindowRow = typeof MaintenanceWindowRow.Type
+
+export const MAINTENANCE_WEEKDAYS = ["mon", "tue", "wed", "thu", "fri", "sat", "sun"] as const
+
+const listOf = <K extends string>(key: K, values: ReadonlyArray<string> | undefined) =>
+	values === undefined ? undefined : { [key]: [...values] }
+
+export const toMaintenanceWindowRow = (window: AlertMaintenanceWindowDocument): WindowRow => ({
+	id: window.id,
+	name: window.name,
+	reason: window.reason,
+	matchers: {
+		...listOf("ruleIds", window.matchers.ruleIds),
+		...listOf("tags", window.matchers.tags),
+		...listOf("services", window.matchers.services),
+		...listOf("environments", window.matchers.environments),
+	},
+	schedule:
+		window.schedule._tag === "once"
+			? { type: "once", startsAt: window.schedule.startsAt, endsAt: window.schedule.endsAt }
+			: {
+					type: "weekly",
+					timeZone: window.schedule.timeZone,
+					days: [...window.schedule.days],
+					startTime: window.schedule.startTime,
+					durationMinutes: window.schedule.durationMinutes,
+				},
+	excludeFromBaselines: window.excludeFromBaselines,
+	enabled: window.enabled,
+	nextOccurrence: window.nextOccurrence,
+	createdBy: window.createdBy,
+})
+
+/** `weekly sat,sun 02:00 Europe/Berlin for 120m`, or the one-off window's bounds. */
+export const formatSchedule = (schedule: WindowRow["schedule"]): string =>
+	schedule.type === "once"
+		? `once ${schedule.startsAt ?? "?"} to ${schedule.endsAt ?? "?"}`
+		: `weekly ${Arr.join(schedule.days ?? [], ",")} ${schedule.startTime ?? "?"} ${schedule.timeZone ?? "?"} for ${schedule.durationMinutes ?? "?"}m`
+
+/** The matchers as one line, e.g. `services: checkout AND environments: production`. */
+export const formatWindowMatchers = (matchers: WindowRow["matchers"]): string => {
+	const entries: ReadonlyArray<readonly [string, ReadonlyArray<string> | undefined]> = [
+		["rules", matchers.ruleIds],
+		["tags", matchers.tags],
+		["services", matchers.services],
+		["environments", matchers.environments],
+	]
+	const parts = Arr.flatMap(entries, ([label, values]) =>
+		values === undefined || values.length === 0 ? [] : [`${label}: ${Arr.join(values, ", ")}`],
+	)
+	return parts.length === 0 ? "-" : Arr.join(parts, " AND ")
+}
+
+const formatNext = (window: WindowRow) =>
+	window.nextOccurrence === null
+		? "-"
+		: `${window.nextOccurrence.startsAt} to ${window.nextOccurrence.endsAt}`
+
+/** Only service and environment matchers keep hours out of anomaly baselines. */
+const baselineExclusion = (window: WindowRow): string => {
+	if (!window.excludeFromBaselines) return "no"
+	const scoped =
+		(window.matchers.services?.length ?? 0) > 0 || (window.matchers.environments?.length ?? 0) > 0
+	return scoped ? "yes" : "no (only service or environment matchers affect baselines)"
+}
+
+export const maintenanceWindowFields = (window: WindowRow) =>
+	doc.fields([
+		["ID", window.id],
+		["Name", window.name],
+		["Reason", window.reason ?? "-"],
+		["Schedule", formatSchedule(window.schedule)],
+		["Matches", formatWindowMatchers(window.matchers)],
+		["Next occurrence", formatNext(window)],
+		["Enabled", window.enabled ? "yes" : "no"],
+		["Excluded from baselines", baselineExclusion(window)],
+	])
+
+export const maintenanceWindowTableRow = (window: WindowRow) => [
+	window.id,
+	window.name,
+	formatSchedule(window.schedule),
+	formatWindowMatchers(window.matchers),
+	formatNext(window),
+	window.enabled ? "yes" : "no",
+]
+
+const failWith = (pipeName: string) => (error: AlertForbiddenError | AlertPersistenceError) =>
+	Effect.fail(toMcpHttpError(pipeName)(error))
+
+/** create_maintenance_window failures: an invalid schedule or matcher is the caller's to fix. */
+export const createWindowErrors = {
+	"@maple/http/errors/AlertValidationError": (error: AlertValidationError) =>
+		Effect.fail(
+			new McpInvalidInputError({
+				message: Arr.join(
+					[
+						`Invalid maintenance window: ${error.message}`,
+						...Arr.filter(error.details, (detail) => detail !== error.message),
+					],
+					". ",
+				),
+			}),
+		),
+	"@maple/http/errors/AlertForbiddenError": failWith("create_maintenance_window"),
+	"@maple/http/errors/AlertPersistenceError": failWith("create_maintenance_window"),
+}
+
+/** delete_maintenance_window failures: an unknown id is invalid input on maintenance_window_id. */
+export const deleteWindowErrors = {
+	"@maple/http/errors/AlertMaintenanceWindowNotFoundError": (error: AlertMaintenanceWindowNotFoundError) =>
+		Effect.fail(
+			new McpInvalidInputError({
+				message: `Maintenance window not found: ${error.maintenanceWindowId}. Use list_maintenance_windows to find window IDs.`,
+				parameter: "maintenance_window_id",
+			}),
+		),
+	"@maple/http/errors/AlertForbiddenError": failWith("delete_maintenance_window"),
+	"@maple/http/errors/AlertPersistenceError": failWith("delete_maintenance_window"),
+}

apps/ai/src/mcp/lib/params.ts

@@ -21,6 +21,7 @@ import { decodePublicId, PublicIdPrefixes } from "@maple/domain/http/v2"
 import {
 	AlertDestinationId,
 	AlertIncidentId,
+	AlertMaintenanceWindowId,
 	AlertRuleId,
 	AlertSilenceId,
 	DashboardId,
@@ -166,6 +167,11 @@ const RESOURCE_IDS = {
 		schema: EscalationChainId,
 		noun: "escalation chain",
 	},
+	alertMaintenanceWindow: {
+		prefix: PublicIdPrefixes.alertMaintenanceWindow,
+		schema: AlertMaintenanceWindowId,
+		noun: "maintenance window",
+	},
 	oncallSchedule: {
 		prefix: PublicIdPrefixes.oncallSchedule,
 		schema: OnCallScheduleId,

apps/ai/src/mcp/resources/instructions.ts

@@ -118,6 +118,7 @@ first occurrences ──> (candidate) ──> issue in \`triage\`
 - Deploy verification: service_deployments (versions per service, newest vs previous) -> compare_periods around the rollout. Route usage over up to 90 days: route_usage. Silence check before calling an outage: ingest_freshness. Volume per service: ingest_usage. Database query shapes by volume: db_query_volume
 - Alert management: list_alert_rules / list_alert_destinations -> get_alert_rule -> preview_alert_rule (dry-run before saving; a window with no data is a blind rule, not a healthy one) -> create_alert_rule / update_alert_rule / delete_alert_rule -> list_alert_incidents
 - Paging step by step until someone acknowledges: list_escalation_chains / create_escalation_chain (steps of destinations + wait_minutes) / update_escalation_chain / delete_escalation_chain; attach to a rule with create_alert_rule / update_alert_rule escalation_chain_id. The rule's own destinations still fire at once.
+- Planned quiet periods (a nightly job, a weekly maintenance slot): create_maintenance_window (once or weekly, with matchers) / list_maintenance_windows / delete_maintenance_window. Each occurrence silences notifications while it runs and, for services or environments, keeps its hours out of anomaly baselines.
 - Who is on call when: list_oncall_schedules / who_is_on_call (schedule id or name, optional at) / create_oncall_schedule (layers of workspace members rotating daily, weekly or every N hours) / update_oncall_schedule / delete_oncall_schedule; cover a window with create_oncall_override / delete_oncall_override.
 - Quieting alerts for a window (maintenance, a known outage): create_alert_silence (matchers + duration_minutes or ends_at) / list_alert_silences / end_alert_silence. Incidents still open; only notifications are held back.
 - Uptime: list_uptime_monitors is every http/tcp/dns check and heartbeat with its status and last check; a failed check's trace id goes to inspect_trace. Admins manage them with create_uptime_monitor / update_uptime_monitor (enabled=false pauses) / delete_uptime_monitor. A down monitor opens an alert incident with signal type \`uptime\`; its rule is managed only through the monitor.