Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
import { apiFetchJSON, apiFetch } from '@/utils/apiClient';
import {
assertAPIResponseOK,
arrayOrEmpty,
objectArrayFieldOrEmpty,
promoteLegacyAlertIdentifier,
withAPIErrorStatusFallback,
withAPIErrorStatusNull,
} from './responseUtils';
import { logger } from '@/utils/logger';
import { consumeJSONEventStream } from './streaming';
import type { InvestigationOutcome } from './patrol';
import type {
AISettings,
AISettingsUpdateRequest,
AITestResult,
AIProviderTestResult,
AIExecuteResponse,
AIStreamEvent,
AICostSummary,
} from '@/types/ai';
import type {
AnomaliesResponse,
IntelligenceSummary,
LearningStatusResponse,
ResourceIntelligence,
} from '@/types/aiIntelligence';
import type { PatrolActionReference } from '@/types/actionAudit';
export class AIAPI {
private static baseUrl = '/api';
// Get AI settings
static async getSettings(): Promise<AISettings> {
return apiFetchJSON(`${this.baseUrl}/settings/ai`) as Promise<AISettings>;
}
// Update AI settings
static async updateSettings(settings: AISettingsUpdateRequest): Promise<AISettings> {
return apiFetchJSON(`${this.baseUrl}/settings/ai/update`, {
method: 'PUT',
body: JSON.stringify(settings),
}) as Promise<AISettings>;
}
// Test AI connection
static async testConnection(): Promise<AITestResult> {
return apiFetchJSON(`${this.baseUrl}/ai/test`, {
method: 'POST',
}) as Promise<AITestResult>;
}
// Test a specific provider connection
static async testProvider(provider: string, model?: string): Promise<AIProviderTestResult> {
const body = model?.trim() ? JSON.stringify({ model: model.trim() }) : undefined;
return apiFetchJSON(`${this.baseUrl}/ai/test/${encodeURIComponent(provider)}`, {
method: 'POST',
...(body ? { body } : {}),
}) as Promise<AIProviderTestResult>;
}
// Get available models from the AI provider
static async getModels(): Promise<{
models: { id: string; name: string; description?: string; notable?: boolean }[];
error?: string;
}> {
return apiFetchJSON(`${this.baseUrl}/ai/models`) as Promise<{
models: { id: string; name: string; description?: string; notable?: boolean }[];
error?: string;
}>;
}
// Get AI cost/usage summary
static async getCostSummary(days = 30): Promise<AICostSummary> {
const search = new URLSearchParams({ days: String(days) });
return apiFetchJSON(
`${this.baseUrl}/ai/cost/summary?${search.toString()}`,
) as Promise<AICostSummary>;
}
// Reset AI usage history (admin-only)
static async resetCostHistory(): Promise<{ ok: boolean; backup_file?: string }> {
return apiFetchJSON(`${this.baseUrl}/ai/cost/reset`, {
method: 'POST',
body: JSON.stringify({}),
}) as Promise<{ ok: boolean; backup_file?: string }>;
}
static async exportCostHistory(days = 30, format: 'json' | 'csv' = 'csv'): Promise<Response> {
const search = new URLSearchParams({
days: String(days),
format,
});
return apiFetch(`${this.baseUrl}/ai/cost/export?${search.toString()}`, { method: 'GET' });
}
// ============================================
// AI Intelligence API - Patterns, Predictions, Correlations
// ============================================
// Get unified findings (alerts + AI findings)
static async getUnifiedFindings(options?: {
resourceId?: string;
source?: string;
includeResolved?: boolean;
}): Promise<UnifiedFindingsResponse> {
const params = new URLSearchParams();
if (options?.resourceId) params.set('resource_id', options.resourceId);
if (options?.source) params.set('source', options.source);
if (options?.includeResolved) params.set('include_resolved', '1');
const query = params.toString();
const response = (await apiFetchJSON(
`${this.baseUrl}/ai/unified/findings${query ? `?${query}` : ''}`,
)) as UnifiedFindingsResponse;
return {
...response,
findings: arrayOrEmpty<UnifiedFindingRecord>(response.findings).map((finding) =>
promoteLegacyAlertIdentifier(
finding as UnifiedFindingRecord & { alert_identifier?: string },
),
),
};
}
// Get current anomalies (real-time baseline deviation detection)
// Returns metrics that are currently deviating significantly from learned baselines
static async getAnomalies(resourceId?: string): Promise<AnomaliesResponse> {
const params = resourceId ? `?resource_id=${encodeURIComponent(resourceId)}` : '';
return apiFetchJSON(
`${this.baseUrl}/ai/intelligence/anomalies${params}`,
) as Promise<AnomaliesResponse>;
}
// Get learning/baseline status (FREE - no license required)
// Shows how many resources have been baselined and the overall learning state
static async getLearningStatus(): Promise<LearningStatusResponse> {
return apiFetchJSON(
`${this.baseUrl}/ai/intelligence/learning`,
) as Promise<LearningStatusResponse>;
}
private static async fetchIntelligence(resourceId?: string): Promise<unknown> {
const params = resourceId ? `?resource_id=${encodeURIComponent(resourceId)}` : '';
return apiFetchJSON(`${this.baseUrl}/ai/intelligence${params}`);
}
// Get the canonical infrastructure-wide intelligence summary
static async getIntelligenceSummary(): Promise<IntelligenceSummary> {
return (await this.fetchIntelligence()) as IntelligenceSummary;
}
// Get canonical intelligence for a single resource
static async getResourceIntelligence(resourceId: string): Promise<ResourceIntelligence> {
return (await this.fetchIntelligence(resourceId)) as ResourceIntelligence;
}
// Analyze a Kubernetes cluster with AI
static async analyzeKubernetesCluster(clusterId: string): Promise<AIExecuteResponse> {
return apiFetchJSON(`${this.baseUrl}/ai/kubernetes/analyze`, {
method: 'POST',
body: JSON.stringify({ cluster_id: clusterId }),
}) as Promise<AIExecuteResponse>;
}
// Run a single command (for approved commands)
static async runCommand(request: {
command: string;
target_type: string;
target_id: string;
run_on_host: boolean;
vmid?: string | number;
target_host?: string; // Explicit host for command routing
}): Promise<{ output: string; success: boolean; error?: string }> {
// Ensure run_on_host is explicitly a boolean (not undefined)
const sanitizedRequest = {
command: request.command,
target_type: request.target_type,
target_id: request.target_id,
run_on_host: Boolean(request.run_on_host),
...(request.vmid ? { vmid: String(request.vmid) } : {}),
...(request.target_host ? { target_host: request.target_host } : {}),
};
const body = JSON.stringify(sanitizedRequest);
logger.debug('[AI] runCommand', { request: sanitizedRequest, bodyLength: body.length });
return apiFetchJSON(`${this.baseUrl}/ai/run-command`, {
method: 'POST',
body,
}) as Promise<{ output: string; success: boolean; error?: string }>;
}
// Investigate an alert with AI (one-click investigation)
static async investigateAlert(
request: {
alertIdentifier: string;
resource_id: string;
resource_name: string;
resource_type: string;
alert_type: string;
level: string;
value: number;
threshold: number;
message: string;
duration: string;
node?: string;
vmid?: number;
},
onEvent: (event: AIStreamEvent) => void,
signal?: AbortSignal,
): Promise<void> {
logger.debug('[AI] Starting alert investigation', request);
const response = await apiFetch(`${this.baseUrl}/ai/investigate-alert`, {
method: 'POST',
body: JSON.stringify(request),
headers: {
'Content-Type': 'application/json',
Accept: 'text/event-stream',
},
signal,
});
await assertAPIResponseOK(response, `Request failed with status ${response.status}`);
await consumeJSONEventStream<AIStreamEvent>(response, {
onEvent: (event) => {
onEvent(event);
},
onParseError: (line) => {
logger.error('[AI] Failed to parse investigation event:', { line });
},
onTimeout: () => {
logger.warn('[AI] Alert investigation stream timeout');
},
});
}
// ============================================
// Investigation Fix Approvals
// ============================================
// Get pending approval requests (investigation fixes waiting for user approval)
static async getPendingApprovals(): Promise<ApprovalRequest[]> {
const response = (await withAPIErrorStatusFallback(
apiFetchJSON(`${this.baseUrl}/ai/approvals`),
402,
{ approvals: [] },
)) as {
approvals: ApprovalRequest[];
};
return objectArrayFieldOrEmpty<ApprovalRequest>(response, 'approvals');
}
// Approve and execute an investigation fix
static async approveInvestigationFix(approvalId: string): Promise<ApprovalExecutionResult> {
return apiFetchJSON(`${this.baseUrl}/ai/approvals/${encodeURIComponent(approvalId)}/approve`, {
method: 'POST',
}) as Promise<ApprovalExecutionResult>;
}
static async approvePendingApproval(approvalId: string): Promise<ApprovalDecisionResult> {
return apiFetchJSON(`${this.baseUrl}/ai/approvals/${encodeURIComponent(approvalId)}/approve`, {
method: 'POST',
}) as Promise<ApprovalDecisionResult>;
}
// Deny an investigation fix
static async denyInvestigationFix(approvalId: string, reason?: string): Promise<ApprovalRequest> {
return apiFetchJSON(`${this.baseUrl}/ai/approvals/${encodeURIComponent(approvalId)}/deny`, {
method: 'POST',
body: JSON.stringify({ reason: reason || 'User declined' }),
}) as Promise<ApprovalRequest>;
}
static async denyPendingApproval(approvalId: string, reason?: string): Promise<ApprovalRequest> {
return apiFetchJSON(`${this.baseUrl}/ai/approvals/${encodeURIComponent(approvalId)}/deny`, {
method: 'POST',
body: JSON.stringify({ reason: reason || 'User declined' }),
}) as Promise<ApprovalRequest>;
}
// Get investigation details for a finding (includes proposed fix)
static async getInvestigation(findingId: string): Promise<InvestigationSession | null> {
return (await withAPIErrorStatusNull(
apiFetchJSON(`${this.baseUrl}/ai/findings/${encodeURIComponent(findingId)}/investigation`),
404,
)) as InvestigationSession | null;
}
// Re-create an approval for an investigation fix (when original approval expired)
static async reapproveInvestigationFix(
findingId: string,
): Promise<{ approval_id: string; message: string }> {
return apiFetchJSON(`${this.baseUrl}/ai/findings/${encodeURIComponent(findingId)}/reapprove`, {
method: 'POST',
}) as Promise<{ approval_id: string; message: string }>;
}
}
// ============================================
// Phase 7 Type Definitions
// ============================================
export interface InvestigationRecordSubject {
resource_id: string;
resource_name?: string;
resource_type?: string;
node?: string;
}
export interface InvestigationRecordTrigger {
finding_key?: string;
source?: string;
severity?: string;
category?: string;
title?: string;
detected_at: string;
description?: string;
cause?: string;
}
export interface InvestigationRecordEvidence {
id?: string;
kind: string;
summary?: string;
}
export interface InvestigationRecordFix {
id: string;
description: string;
commands?: string[];
risk_level?: string;
destructive: boolean;
target_host?: string;
rationale?: string;
}
export interface InvestigationRecord {
id: string;
finding_id: string;
session_id?: string;
subject: InvestigationRecordSubject;
trigger: InvestigationRecordTrigger;
status: string;
outcome?: string;
confidence?: 'low' | 'medium' | 'high';
evidence: InvestigationRecordEvidence[];
conclusion?: string;
impact?: string;
recommended_action?: string;
proposed_fix?: InvestigationRecordFix;
verification: string[];
rollback: string[];
tools_used: string[];
started_at: string;
completed_at?: string;
approval_id?: string;
action?: PatrolActionReference;
error?: string;
}
export interface UnifiedFindingRecord {
id: string;
source: string;
severity: string;
category: string;
resource_id: string;
resource_name: string;
resource_type: string;
resource_criticality?: 'high' | 'medium' | 'low' | '';
node?: string;
title: string;
description: string;
impact?: string;
previous_resolved_fix_summary?: string;
recommendation?: string;
evidence?: string;
alertIdentifier?: string;
alert_type?: string;
value?: number;
threshold?: number;
is_threshold?: boolean;
ai_context?: string;
root_cause_id?: string;
correlated_ids?: string[];
remediation_id?: string;
ai_confidence?: number;
enhanced_by_ai?: boolean;
ai_enhanced_at?: string;
// Investigation fields (snake_case from Go backend)
investigation_session_id?: string;
investigation_status?: string;
investigation_outcome?: string;
last_investigated_at?: string;
investigation_attempts?: number;
investigation_record?: InvestigationRecord;
loop_state?: string;
lifecycle?: Array<{
at: string;
type: string;
message?: string;
from?: string;
to?: string;
metadata?: Record<string, string>;
}>;
regression_count?: number;
last_regression_at?: string;
detected_at: string;
last_seen_at?: string;
resolved_at?: string;
// auto_resolved distinguishes Pulse's own auto-detection of the condition
// clearing (true) from an operator-driven manual "Mark resolved" (false),
// so the surface can attribute who closed the loop.
auto_resolved?: boolean;
acknowledged_at?: string;
snoozed_until?: string;
dismissed_reason?: string;
user_note?: string;
suppressed?: boolean;
times_raised?: number;
// remind_at carries the will_fix_later wake-up deadline. When dismissed_reason
// === 'will_fix_later', the finding stays quiet until this timestamp passes;
// afterwards the next re-detection clears the dismissal.
remind_at?: string;
status?: string;
}
export interface UnifiedFindingsResponse {
findings: UnifiedFindingRecord[];
count?: number;
active_count?: number;
}
// ============================================
// Investigation Fix Approval Types
// ============================================
export type ApprovalStatus = 'pending' | 'approved' | 'denied' | 'expired';
export type RiskLevel = 'low' | 'medium' | 'high';
export interface ApprovalActionPlan {
actionId?: string;
requestId?: string;
summary?: string;
message?: string;
requiresApproval?: boolean;
approvalPolicy?: string;
blastRadius?: string;
predictedBlastRadius?: string[];
rollbackAvailable?: boolean;
planHash?: string;
expiresAt?: string;
}
export interface ApprovalContextConfidence {
level?: string;
summary?: string;
evidence?: string[];
}
export interface ApprovalActionPreflight {
target?: string;
currentState?: string;
intendedChange?: string;
dryRunAvailable: boolean;
dryRunSummary?: string;
safetyChecks?: string[];
verificationSteps?: string[];
generatedAt?: string;
}
export interface ApprovalRequest {
id: string;
orgId?: string;
executionId?: string;
toolId: string; // "investigation_fix" for patrol findings
command: string;
targetType: string;
targetId: string;
targetName: string;
context: string;
requestedBy?: string;
riskLevel: RiskLevel;
status: ApprovalStatus;
requestedAt: string;
expiresAt: string;
decidedAt?: string;
decidedBy?: string;
denyReason?: string;
commandHash?: string;
consumed?: boolean;
plan?: ApprovalActionPlan;
contextConfidence?: ApprovalContextConfidence;
preflight?: ApprovalActionPreflight;
}
export interface ApprovalExecutionResult {
approved: boolean;
executed: boolean;
success: boolean;
output: string;
exit_code: number;
error?: string;
finding_id: string;
message: string;
}
export type ApprovalDecisionResult =
| ApprovalExecutionResult
| {
approved: boolean;
executed?: boolean;
success?: boolean;
message?: string;
error?: string;
approval_id?: string;
request?: ApprovalRequest;
};
// ============================================
// Investigation Session Types
// ============================================
export type InvestigationStatus =
'pending' | 'running' | 'completed' | 'failed' | 'needs_attention';
export interface ProposedFix {
id: string;
description: string;
commands?: string[];
risk_level?: 'low' | 'medium' | 'high' | 'critical';
destructive: boolean;
target_host?: string;
rationale?: string;
}
export interface InvestigationSession {
id: string;
finding_id: string;
session_id: string;
status: InvestigationStatus;
started_at: string;
completed_at?: string;
turn_count: number;
outcome?: InvestigationOutcome;
tools_available?: string[];
tools_used?: string[];
evidence_ids?: string[];
proposed_fix?: ProposedFix;
approval_id?: string;
action?: PatrolActionReference;
summary?: string;
error?: string;
}