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
/**
* Pulse Patrol API client
* Provides access to background AI monitoring findings and status
*/
import { apiFetchJSON } from '@/utils/apiClient';
import { arrayOrEmpty, promoteLegacyAlertIdentifier } from './responseUtils';
import type { InvestigationRecord } from './ai';
import type { ResourceCriticality } from './resourceOperatorState';
import type { PatrolActionReference } from '@/types/actionAudit';
import type { PatrolModelReadinessSnapshot } from '@/types/ai';
export type FindingSeverity = 'info' | 'watch' | 'warning' | 'critical';
export type FindingCategory =
'performance' | 'capacity' | 'reliability' | 'backup' | 'security' | 'general';
export interface Finding {
id: string;
key?: string;
severity: FindingSeverity;
category: FindingCategory;
resource_id: string;
resource_name: string;
resource_type: string; // node, vm, system-container, app-container, storage, pbs, host_raid
resource_criticality?: ResourceCriticality;
node?: string;
title: string;
description: string;
impact?: string;
previous_resolved_fix_summary?: string;
recommendation?: string;
evidence?: string;
detected_at: string;
last_seen_at: string;
resolved_at?: string;
auto_resolved: boolean;
acknowledged_at?: string;
snoozed_until?: string; // Finding hidden until this time
alertIdentifier?: string;
// User feedback fields (LLM memory system)
dismissed_reason?: 'not_an_issue' | 'expected_behavior' | 'will_fix_later';
user_note?: string;
times_raised: number;
suppressed: boolean;
// remind_at carries the will_fix_later wake-up deadline; the finding stays
// quiet on re-detection until this timestamp passes, then the next
// re-detection clears the dismissal and emits a "reminded" lifecycle event.
remind_at?: string;
// Investigation fields (Patrol mode)
investigation_session_id?: string;
investigation_status?: InvestigationStatus;
investigation_outcome?: InvestigationOutcome;
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;
// Deterministic capacity forecast (trend/eta) computed by Patrol
// independently of the model-authored prose body. Surfaced as a first-class
// urgency signal. Present only for capacity-relevant findings whose resource
// has enough utilization history to compute a trend.
capacity_forecast?: CapacityForecast;
// flapping is present while the finding's open/resolved state has changed
// at least four times inside the last 24 hours. The store collapses those
// transitions into one lifecycle row; this summary carries the count.
flapping?: FindingFlapping;
// mirrors_alert_id / mirrors_alert_type name the active alert this finding
// restates (same resource, same condition). Patrol stamps them after every
// run so the UI can fold the finding under the alert instead of listing the
// same problem twice.
mirrors_alert_id?: string;
mirrors_alert_type?: string;
}
/**
* FindingFlapping summarises open/resolved churn on one finding. Mirrors
* internal/ai FindingFlapping on the wire.
*/
export interface FindingFlapping {
transition_count: number;
window_hours: number;
first_transition_at: string;
last_transition_at: string;
}
/**
* CapacityForecast is a deterministic, backend-computed capacity trend for a
* finding's resource. Unlike the model-authored prose (description/impact/
* recommendation), this is a computed fact and is the operator's primary
* urgency signal: "fills in ~N days at +X%/day".
*/
export interface CapacityForecast {
metric?: string; // e.g. 'storage', 'disk'
current_pct: number; // current utilization %
daily_change: number; // avg % change per day (negative = declining)
days_to_full: number; // days to 100% at current rate; -1 if stable/declining
}
export type InvestigationStatus =
'pending' | 'running' | 'completed' | 'failed' | 'needs_attention';
// Every outcome the backend records (InvestigationOutcome in
// internal/ai/findings.go). The findings store keys its accepted values by
// this union, so a new outcome must be added here first.
export type InvestigationOutcome =
| 'resolved'
| 'fix_queued'
| 'fix_executed'
| 'fix_failed'
| 'fix_rejected'
| 'needs_attention'
| 'cannot_fix'
| 'timed_out'
| 'unclassified'
| 'interrupted'
| 'fix_verified'
| 'fix_verification_failed'
| 'fix_verification_unknown';
export type PatrolAutonomyLevel = 'monitor' | 'approval' | 'assisted' | 'full';
export type PatrolObjectiveStatus = 'active' | 'paused' | 'archived';
export type PatrolObjectiveCoverageState = 'covered' | 'degraded' | 'uncovered';
export interface PatrolObjectiveCoverage {
state: PatrolObjectiveCoverageState;
reason_code: string;
summary: string;
observer_id?: string;
observer_version?: number;
valid_until?: string;
last_evidence_at?: string;
}
export interface PatrolObjective {
id: string;
brief: string;
optional_context?: string;
scope: { resource_ids: string[] };
status: PatrolObjectiveStatus;
coverage: PatrolObjectiveCoverage;
revision: number;
created_by?: string;
updated_by?: string;
created_at: string;
updated_at: string;
}
export interface PatrolObjectiveCreate {
brief: string;
optional_context?: string;
resource_ids?: string[];
}
export interface PatrolObjectiveUpdate {
revision: number;
brief?: string;
optional_context?: string;
resource_ids?: string[];
status?: PatrolObjectiveStatus;
}
export type PatrolAutopilotStatusCode =
| 'active'
| 'not_requested'
| 'acknowledgement_required'
| 'acknowledgement_stale_version'
| 'acknowledgement_wrong_org'
| 'acknowledgement_wrong_actor'
| 'acknowledgement_user_required'
| 'acknowledgement_digest_invalid'
| 'acknowledgement_expired'
| 'acknowledgement_revoked'
| 'acknowledgement_conflict'
| 'activation_digest_invalid'
| 'legacy_unlock_ignored'
| 'acknowledgement_store_unavailable'
| 'acknowledgement_activation_raced'
| 'license_required';
export interface PatrolAutopilotAcceptedLimits {
policyAllowlistRequired: boolean;
emergencyStopHonored: boolean;
approvalFloorsHonored: boolean;
verificationReconciledWhenSupported: boolean;
evidenceClassDisclosed: boolean;
inconclusiveOutcomeAllowed: boolean;
executionSuccessIsNotOutcomeTruth: boolean;
activationRevocationBound?: boolean;
}
export interface PatrolAutopilotStatus {
code: PatrolAutopilotStatusCode;
active: boolean;
currentVersion: number;
acknowledgementVersion?: number;
acknowledgementId?: string;
acknowledgementDigest?: string;
acknowledgedBy?: string;
acceptedAt?: string;
expiresAt?: string;
acceptedScope: string[];
acceptedLimits: PatrolAutopilotAcceptedLimits;
}
export async function getPatrolObjectives(): Promise<PatrolObjective[]> {
const response = await apiFetchJSON<{ objectives?: PatrolObjective[] }>(
'/api/ai/patrol/objectives',
);
return arrayOrEmpty(response.objectives);
}
export async function createPatrolObjective(
input: PatrolObjectiveCreate,
): Promise<PatrolObjective> {
return apiFetchJSON<PatrolObjective>('/api/ai/patrol/objectives', {
method: 'POST',
body: JSON.stringify(input),
headers: { 'Content-Type': 'application/json' },
});
}
export async function updatePatrolObjective(
objectiveId: string,
input: PatrolObjectiveUpdate,
): Promise<PatrolObjective> {
return apiFetchJSON<PatrolObjective>(
`/api/ai/patrol/objectives/${encodeURIComponent(objectiveId)}`,
{
method: 'PATCH',
body: JSON.stringify(input),
headers: { 'Content-Type': 'application/json' },
},
);
}
export async function deletePatrolObjective(objectiveId: string, revision: number): Promise<void> {
await apiFetchJSON<void>(
`/api/ai/patrol/objectives/${encodeURIComponent(objectiveId)}?revision=${encodeURIComponent(String(revision))}`,
{ method: 'DELETE' },
);
}
export interface PatrolAutonomySettings {
autonomy_level: PatrolAutonomyLevel;
requested_autonomy_level: PatrolAutonomyLevel;
effective_autonomy_level: PatrolAutonomyLevel;
full_mode_unlocked: boolean;
autopilot_acknowledgement: PatrolAutopilotStatus;
investigation_budget: number; // Max turns per investigation (5-30)
investigation_timeout_sec: number; // Max seconds per investigation (60-600)
/** True when the install never chose a mode and Pro runs Ask first by default. */
default_mode_applied?: boolean;
}
export interface PatrolAutonomyUpdate {
autonomy_level: PatrolAutonomyLevel;
acknowledgement_id?: string;
investigation_budget: number;
investigation_timeout_sec: number;
}
export interface Investigation {
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[];
summary?: string;
error?: string;
proposed_fix?: ProposedFix;
approval_id?: string;
action?: PatrolActionReference;
}
export interface ProposedFix {
id: string;
description: string;
commands?: string[];
risk_level?: string;
destructive: boolean;
target_host?: string;
rationale?: string;
}
export interface InvestigationMessages {
investigation_id: string;
session_id: string;
messages: ChatMessage[];
}
export interface ChatMessage {
id: string;
role: 'user' | 'assistant' | 'system';
content: string;
reasoning_content?: string;
tool_calls?: ChatToolCall[];
tool_result?: ChatToolResult;
timestamp: string;
}
export interface ChatToolCall {
id: string;
name: string;
input: Record<string, unknown>;
output?: string;
success?: boolean;
}
export interface ChatToolResult {
tool_use_id: string;
content: string;
is_error?: boolean;
}
export interface FindingsSummary {
critical: number;
warning: number;
watch: number;
info: number;
}
export type LicenseStatus = 'none' | 'active' | 'expired' | 'grace_period';
export type PatrolRuntimeState = 'unavailable' | 'disabled' | 'running' | 'blocked' | 'active';
export type PatrolReadinessStatus = 'ready' | 'warning' | 'not_ready';
export interface PatrolReadinessCheck {
id: string;
status: PatrolReadinessStatus;
cause?: string;
label: string;
message: string;
action?: string;
}
export interface PatrolReadiness {
status: PatrolReadinessStatus;
ready: boolean;
cause?: string;
summary: string;
provider?: string;
model?: string;
checks: PatrolReadinessCheck[];
}
export interface PatrolTriggerStatus {
running: boolean;
pending_triggers: number;
current_interval_ms: number;
recent_events: number;
is_busy_mode: boolean;
alert_triggers_enabled: boolean;
anomaly_triggers_enabled: boolean;
event_triggers_blocked?: boolean;
event_triggers_blocked_reason?: string;
event_triggers_blocked_message?: string;
}
export interface FindingsTrustSummary {
tracked: number;
currently_active: number;
resolved: number;
auto_resolved: number;
fix_verified: number;
fix_failed: number;
dismissed_as_noise: number;
dismissed_as_expected: number;
dismissed_as_later: number;
suppressed: number;
regressed_at_least_once: number;
}
export interface PatrolStatus {
runtime_state: PatrolRuntimeState;
running: boolean;
current_run_id?: string;
current_run_started_at?: string;
enabled: boolean;
last_patrol_at?: string;
last_activity_at?: string;
trigger_status?: PatrolTriggerStatus;
next_patrol_at?: string;
last_duration_ms: number;
resources_checked: number;
findings_count: number;
error_count: number;
healthy: boolean;
interval_ms: number; // Patrol interval in milliseconds
fixed_count: number; // Number of issues remediated by Patrol
blocked_reason?: string; // Canonical server-authored Patrol block reason.
blocked_cause?: string;
blocked_at?: string;
license_required?: boolean;
license_status?: LicenseStatus;
upgrade_url?: string;
readiness?: PatrolReadiness;
summary: FindingsSummary;
trust?: FindingsTrustSummary;
}
/**
* Get the current Pulse Patrol status
*/
export async function getPatrolStatus(): Promise<PatrolStatus> {
return apiFetchJSON<PatrolStatus>('/api/ai/patrol/status');
}
const DEFAULT_PATROL_FINDINGS_HISTORY_LIMIT = 200;
const MAX_PATROL_FINDINGS_HISTORY_LIMIT = 500;
function normalizePatrolFindingsLimit(limit: number | undefined): number {
if (limit === undefined || !Number.isFinite(limit)) {
return DEFAULT_PATROL_FINDINGS_HISTORY_LIMIT;
}
const normalized = Math.floor(limit);
if (normalized < 1) {
return DEFAULT_PATROL_FINDINGS_HISTORY_LIMIT;
}
if (normalized > MAX_PATROL_FINDINGS_HISTORY_LIMIT) {
return MAX_PATROL_FINDINGS_HISTORY_LIMIT;
}
return normalized;
}
export async function getPatrolFindings(options?: {
includeResolved?: boolean;
limit?: number;
}): Promise<Finding[]> {
const search = new URLSearchParams();
if (options?.includeResolved) {
search.set('include_resolved', '1');
search.set('limit', String(normalizePatrolFindingsLimit(options.limit)));
} else if (options?.limit !== undefined) {
search.set('limit', String(normalizePatrolFindingsLimit(options.limit)));
}
const query = search.toString();
const path = query ? `/api/ai/patrol/findings?${query}` : '/api/ai/patrol/findings';
const findings = await apiFetchJSON<Finding[]>(path);
return arrayOrEmpty<Finding>(findings).map((finding) =>
promoteLegacyAlertIdentifier(finding as Finding & { alert_identifier?: string }),
);
}
/**
* Acknowledge a finding (marks as seen but keeps visible, like alert acknowledgement)
* Finding will auto-resolve when the underlying condition clears.
*/
export async function acknowledgeFinding(
findingId: string,
): Promise<{ success: boolean; message: string }> {
return apiFetchJSON('/api/ai/patrol/acknowledge', {
method: 'POST',
body: JSON.stringify({ finding_id: findingId }),
});
}
/**
* Manually mark a finding as resolved.
*
* Use this when the operator has fixed the issue out-of-band and wants Pulse
* to close the loop without waiting for auto-resolution. The server records
* `auto=false` so analytics can distinguish operator-driven resolution from
* Pulse's own auto-resolution; subsequent re-detection of the same finding
* still flows through the regression path and captures
* `previous_resolved_fix_summary` in operational memory.
*/
export async function resolveFinding(
findingId: string,
): Promise<{ success: boolean; message: string }> {
return apiFetchJSON('/api/ai/patrol/resolve', {
method: 'POST',
body: JSON.stringify({ finding_id: findingId }),
});
}
/**
* Snooze a finding for a specified duration
* @param findingId The ID of the finding to snooze
* @param durationHours Duration in hours (e.g., 1, 24, 168 for 7 days)
*/
export async function snoozeFinding(
findingId: string,
durationHours: number,
): Promise<{ success: boolean; message: string }> {
return apiFetchJSON('/api/ai/patrol/snooze', {
method: 'POST',
body: JSON.stringify({ finding_id: findingId, duration_hours: durationHours }),
});
}
/**
* Dismiss a finding with a reason (LLM memory feature)
* The LLM will be told not to re-raise this issue in future patrols.
* @param findingId The ID of the finding to dismiss
* @param reason One of: "not_an_issue", "expected_behavior", "will_fix_later"
* @param note Optional freeform explanation
*/
export async function dismissFinding(
findingId: string,
reason: 'not_an_issue' | 'expected_behavior' | 'will_fix_later',
note?: string,
): Promise<{ success: boolean; message: string }> {
return apiFetchJSON('/api/ai/patrol/dismiss', {
method: 'POST',
body: JSON.stringify({ finding_id: findingId, reason, note }),
});
}
/**
* Reopen a dismissed finding.
*
* Dismissed findings are exposed by the backend as finding-backed suppression
* rows, so removing that row performs the canonical undismiss transition.
*/
export async function reopenFinding(
findingId: string,
): Promise<{ success: boolean; message: string }> {
return apiFetchJSON(`/api/ai/patrol/suppressions/${encodeURIComponent(`finding_${findingId}`)}`, {
method: 'DELETE',
});
}
export interface PatrolSuppressionRule {
id: string;
resource_id?: string;
resource_name?: string;
category?: string;
description: string;
created_at: string;
created_from?: string;
finding_id?: string;
dismissed_reason?: string;
}
export function isManualSuppressionRule(rule: PatrolSuppressionRule): boolean {
return (
rule.created_from === 'manual' &&
rule.id.startsWith('rule_') &&
!rule.finding_id &&
!rule.dismissed_reason
);
}
/** Read the existing collection without silently falling back to another tenant. */
export async function getSuppressionRules(
orgID: string,
signal?: AbortSignal,
): Promise<PatrolSuppressionRule[]> {
const data = await apiFetchJSON<unknown>('/api/ai/patrol/suppressions', {
expectedOrgID: orgID,
retry: false,
signal,
});
// The existing Go store serialises an empty nil slice as null.
if (data === null) return [];
const ids = new Set<string>();
if (
!Array.isArray(data) ||
data.some((row) => {
if (!row || typeof row !== 'object') return true;
if (
typeof row.id !== 'string' ||
!row.id.trim() ||
ids.has(row.id) ||
typeof row.description !== 'string' ||
typeof row.created_at !== 'string' ||
[
'resource_id',
'resource_name',
'category',
'created_from',
'finding_id',
'dismissed_reason',
].some((key) => row[key] !== undefined && typeof row[key] !== 'string')
)
return true;
ids.add(row.id);
return false;
})
) {
throw new Error('Patrol returned an invalid rule list. Reload before making changes.');
}
return data as PatrolSuppressionRule[];
}
/** Removing a manual rule never calls the finding-specific Reopen path. */
export async function deleteManualSuppressionRule(
rule: PatrolSuppressionRule,
orgID: string,
signal?: AbortSignal,
): Promise<void> {
if (!isManualSuppressionRule(rule)) {
throw new Error('Only manually created rules can be removed here.');
}
const result = await apiFetchJSON<{ success: boolean }>(
`/api/ai/patrol/suppressions/${encodeURIComponent(rule.id)}`,
{ method: 'DELETE', expectedOrgID: orgID, retry: false, signal },
);
if (result?.success !== true) throw new Error('Rule removal was not confirmed.');
}
/**
* Create a permanent suppression rule from a finding.
*
* Unlike dismissFinding (which acts on a single instance), this records a
* durable pattern: future findings on the same {resource, category}
* pair will be auto-dismissed by the backend's
* isSuppressedInternal/MatchesSuppressionRule machinery. Used by the
* per-finding "Create rule from this" button so an operator who has
* been silencing the same noisy pattern repeatedly can promote that
* judgment into a remembered rule rather than dismissing every recurrence.
*
* The description is required by the backend — it's the operator's
* stated reason, surfaced when the rule is later listed or audited.
* This per-finding helper is intentionally narrow: it refuses empty
* resource/category values so a noisy finding cannot accidentally create
* a wildcard suppression rule. Broader rules must come from an explicit
* rule-management surface.
*/
export async function createSuppressionRuleFromFinding(input: {
resourceId: string;
resourceName: string;
category: string;
description: string;
}): Promise<{ success: boolean; message: string; rule: { id: string } }> {
const resourceId = input.resourceId.trim();
const resourceName = input.resourceName.trim() || resourceId;
const category = input.category.trim();
const description = input.description.trim();
if (!resourceId || !category) {
throw new Error('Suppression rules created from a finding require a resource and category');
}
if (!description) {
throw new Error('Suppression rules require a description');
}
return apiFetchJSON('/api/ai/patrol/suppressions', {
method: 'POST',
body: JSON.stringify({
resource_id: resourceId,
resource_name: resourceName,
category,
description,
}),
});
}
/**
* Set or update a user note on a finding
* Notes provide context that Patrol sees on future runs.
* @param findingId The ID of the finding
* @param note The note text (empty string to clear)
*/
export async function setFindingNote(
findingId: string,
note: string,
): Promise<{ success: boolean; message: string }> {
return apiFetchJSON('/api/ai/patrol/findings/note', {
method: 'POST',
body: JSON.stringify({ finding_id: findingId, note }),
});
}
// =============================================================================
// Patrol Mode APIs
// =============================================================================
/**
* Get current Patrol mode settings
*/
export async function getPatrolAutonomySettings(): Promise<PatrolAutonomySettings> {
return apiFetchJSON<PatrolAutonomySettings>('/api/ai/patrol/autonomy');
}
/**
* Update Patrol mode settings
*/
export async function updatePatrolAutonomySettings(
settings: PatrolAutonomyUpdate,
): Promise<{ success: boolean; settings: PatrolAutonomySettings }> {
return apiFetchJSON('/api/ai/patrol/autonomy', {
method: 'PUT',
body: JSON.stringify(settings),
});
}
export async function createPatrolAutopilotAcknowledgement(
acknowledgementId: string,
): Promise<{ created: boolean; acknowledgement: PatrolAutopilotStatus }> {
return apiFetchJSON('/api/ai/patrol/autonomy/acknowledgements', {
method: 'POST',
body: JSON.stringify({ acknowledgement_id: acknowledgementId }),
});
}
export async function revokePatrolAutopilotAcknowledgement(
acknowledgementId: string,
reason = 'Operator revoked Autopilot from Patrol controls.',
): Promise<{ revoked: boolean; created: boolean; acknowledgement_id: string }> {
return apiFetchJSON(
`/api/ai/patrol/autonomy/acknowledgements/${encodeURIComponent(acknowledgementId)}`,
{ method: 'DELETE', body: JSON.stringify({ reason }) },
);
}
/**
* Get investigation details for a finding
*/
export async function getInvestigation(findingId: string): Promise<Investigation> {
return apiFetchJSON<Investigation>(
`/api/ai/findings/${encodeURIComponent(findingId)}/investigation`,
);
}
/**
* Get chat messages for an investigation
*/
export async function getInvestigationMessages(findingId: string): Promise<InvestigationMessages> {
return apiFetchJSON<InvestigationMessages>(
`/api/ai/findings/${encodeURIComponent(findingId)}/investigation/messages`,
);
}
/**
* Trigger re-investigation of a finding
*/
export async function reinvestigateFinding(
findingId: string,
): Promise<{ success: boolean; message: string }> {
return apiFetchJSON(`/api/ai/findings/${encodeURIComponent(findingId)}/reinvestigate`, {
method: 'POST',
});
}
/**
* Severity color mapping for UI
*/
export const severityColors: Record<FindingSeverity, { bg: string; text: string; border: string }> =
{
critical: { bg: 'rgba(220, 38, 38, 0.15)', text: '#ef4444', border: 'rgba(220, 38, 38, 0.3)' },
warning: { bg: 'rgba(234, 179, 8, 0.15)', text: '#eab308', border: 'rgba(234, 179, 8, 0.3)' },
watch: { bg: 'rgba(59, 130, 246, 0.15)', text: '#3b82f6', border: 'rgba(59, 130, 246, 0.3)' },
info: { bg: 'rgba(107, 114, 128, 0.15)', text: '#9ca3af', border: 'rgba(107, 114, 128, 0.3)' },
};
/**
* Format a timestamp for display
*/
export function formatTimestamp(ts: string): string {
const date = new Date(ts);
if (!ts || Number.isNaN(date.getTime())) {
return '';
}
const now = new Date();
const diffMs = now.getTime() - date.getTime();
const diffMins = Math.floor(diffMs / 60000);
const diffHours = Math.floor(diffMs / 3600000);
const diffDays = Math.floor(diffMs / 86400000);
if (diffMins < 1) return 'just now';
if (diffMins < 60) return `${diffMins}m ago`;
if (diffHours < 24) return `${diffHours}h ago`;
if (diffDays < 7) return `${diffDays}d ago`;
return date.toLocaleDateString();
}
/**
* Investigation status labels for UI
*/
export const investigationStatusLabels: Record<InvestigationStatus, string> = {
pending: 'Pending',
running: 'Investigating...',
completed: 'Completed',
failed: 'Failed',
needs_attention: 'Needs Attention',
};
/**
* Investigation outcome labels for UI
*/
export const investigationOutcomeLabels: Record<InvestigationOutcome, string> = {
resolved: 'Resolved',
fix_queued: 'Fix Queued',
fix_executed: 'Fix Executed',
fix_failed: 'Fix Failed',
fix_rejected: 'Fix Rejected',
needs_attention: 'Needs Attention',
cannot_fix: 'Cannot Remediate',
timed_out: 'Timed Out — Will Retry',
unclassified: 'No Clear Conclusion',
interrupted: 'Interrupted — Will Retry',
fix_verified: 'Fix Verified',
fix_verification_failed: 'Verification Failed',
fix_verification_unknown: 'Verification Inconclusive',
};
/**
* Investigation outcome badge colors for UI
*/
export const investigationOutcomeColors: Record<InvestigationOutcome, string> = {
resolved:
'border-green-200 bg-green-50 text-green-700 dark:border-green-800 dark:bg-green-900/25 dark:text-green-300',
fix_queued:
'border-blue-200 bg-blue-50 text-blue-700 dark:border-blue-800 dark:bg-blue-900/25 dark:text-blue-300',
fix_executed:
'border-green-200 bg-green-50 text-green-700 dark:border-green-800 dark:bg-green-900/25 dark:text-green-300',
fix_failed:
'border-red-200 bg-red-50 text-red-700 dark:border-red-800 dark:bg-red-900/25 dark:text-red-300',
fix_rejected:
'border-amber-200 bg-amber-50 text-amber-700 dark:border-amber-800 dark:bg-amber-900/25 dark:text-amber-300',
needs_attention:
'border-amber-200 bg-amber-50 text-amber-700 dark:border-amber-800 dark:bg-amber-900/25 dark:text-amber-300',
cannot_fix: 'border-slate-200 bg-slate-50 text-slate-600',
timed_out:
'border-amber-200 bg-amber-50 text-amber-700 dark:border-amber-800 dark:bg-amber-900/25 dark:text-amber-300',
unclassified:
'border-amber-200 bg-amber-50 text-amber-700 dark:border-amber-800 dark:bg-amber-900/25 dark:text-amber-300',
interrupted: 'border-border bg-surface-alt text-base-content',
fix_verified:
'border-green-200 bg-green-50 text-green-700 dark:border-green-800 dark:bg-green-900/25 dark:text-green-300',
fix_verification_failed:
'border-red-200 bg-red-50 text-red-700 dark:border-red-800 dark:bg-red-900/25 dark:text-red-300',
fix_verification_unknown:
'border-amber-200 bg-amber-50 text-amber-700 dark:border-amber-800 dark:bg-amber-900/25 dark:text-amber-300',
};
// =============================================================================
// Patrol Run History APIs
// =============================================================================
export type PatrolRunStatus = 'healthy' | 'issues_found' | 'critical' | 'error';
export type ToolCallVerificationStatus = 'unknown' | 'verified' | 'unverified' | 'failed';
export interface ToolCallVerification {
status: ToolCallVerificationStatus;
evidenceSummary?: string;
}
export interface ToolCallRecord {
id: string;
tool_name: string;
input: string;
output: string;
success: boolean;
start_time: number;
end_time: number;
duration_ms: number;
verification?: ToolCallVerification;
}
export interface PatrolRunRecord {
id: string;
source?: 'demo' | string;
started_at: string;
completed_at: string;
duration_ms: number;
type: string;
trigger_reason?: string;
scope_resource_ids?: string[];
effective_scope_resource_ids?: string[];
scope_resource_types?: string[];
scope_context?: string;
alertIdentifier?: string;
finding_id?: string;
resources_checked: number;
nodes_checked: number;
guests_checked: number;
docker_checked: number;
storage_checked: number;
hosts_checked: number;
truenas_checked: number;
pbs_checked: number;
pmg_checked: number;
kubernetes_checked: number;
new_findings: number;
existing_findings: number;
rejected_findings: number;
resolved_findings: number;
auto_fix_count: number;
findings_summary: string;
finding_ids?: string[];
error_count: number;
status: PatrolRunStatus;
error_summary?: string;
error_detail?: string;
triage_flags: number;
triage_skipped_llm?: boolean;
ai_analysis?: string;
input_tokens?: number;
output_tokens?: number;
tool_calls?: ToolCallRecord[];
tool_call_count: number;
}
const DEFAULT_PATROL_HISTORY_LIMIT = 30;
const MAX_PATROL_HISTORY_LIMIT = 100;
function normalizePatrolRunRecord(run: PatrolRunRecord | null | undefined): PatrolRunRecord | null {
if (!run || typeof run !== 'object' || Array.isArray(run)) {
return null;
}
const normalized = promoteLegacyAlertIdentifier(
run as PatrolRunRecord & { alert_identifier?: string; truenas_checked?: number },
);
const findingIDs = Array.isArray(normalized.finding_ids) ? normalized.finding_ids : undefined;
return {
...normalized,
...(findingIDs !== undefined ? { finding_ids: findingIDs } : {}),
truenas_checked:
typeof normalized.truenas_checked === 'number' && Number.isFinite(normalized.truenas_checked)
? normalized.truenas_checked
: 0,
};
}
function normalizeHistoryLimit(limit: number): number {
if (!Number.isFinite(limit)) {
return DEFAULT_PATROL_HISTORY_LIMIT;
}
const normalized = Math.floor(limit);
if (normalized < 1) {
return DEFAULT_PATROL_HISTORY_LIMIT;
}
if (normalized > MAX_PATROL_HISTORY_LIMIT) {
return MAX_PATROL_HISTORY_LIMIT;
}
return normalized;
}
async function fetchPatrolRunHistory(search: URLSearchParams): Promise<PatrolRunRecord[]> {
const runs = await apiFetchJSON<PatrolRunRecord[]>(`/api/ai/patrol/runs?${search.toString()}`);
return arrayOrEmpty<PatrolRunRecord>(runs)
.map((run) => normalizePatrolRunRecord(run))
.filter((run): run is PatrolRunRecord => run !== null);
}
async function fetchPatrolRun(path: string): Promise<PatrolRunRecord | null> {
const run = await apiFetchJSON<PatrolRunRecord | null>(path);
return normalizePatrolRunRecord(run);
}
/**
* Get patrol run history
* @param limit Maximum number of runs to return (default: 30)
*/
export async function getPatrolRunHistory(limit: number = 30): Promise<PatrolRunRecord[]> {
const search = new URLSearchParams({
limit: String(normalizeHistoryLimit(limit)),
});
return fetchPatrolRunHistory(search);
}
/**
* Get patrol run history with tool calls included
* @param limit Maximum number of runs to return (default: 30)
*/
export async function getPatrolRunHistoryWithToolCalls(
limit: number = 30,
): Promise<PatrolRunRecord[]> {
const search = new URLSearchParams({
include: 'tool_calls',
limit: String(normalizeHistoryLimit(limit)),
});
return fetchPatrolRunHistory(search);
}
/**
* Get a single patrol run
*/
export async function getPatrolRun(runId: string): Promise<PatrolRunRecord | null> {
return fetchPatrolRun(`/api/ai/patrol/runs/${encodeURIComponent(runId)}`);
}
/**
* Get a single patrol run with tool call details included
*/
export async function getPatrolRunWithToolCalls(runId: string): Promise<PatrolRunRecord | null> {
return fetchPatrolRun(`/api/ai/patrol/runs/${encodeURIComponent(runId)}?include=tool_calls`);
}
/** SSE event from /api/ai/patrol/stream */
export interface PatrolStreamEvent {
// Meta (best-effort; present when backend supports it)
run_id?: string;
seq?: number;
ts_ms?: number;
resync_reason?: 'late_joiner' | 'stale_last_event_id' | 'buffer_rotated';
buffer_start_seq?: number;
buffer_end_seq?: number;
content_truncated?: boolean;
type:
| 'snapshot'
| 'start'
| 'content'
| 'phase'
| 'thinking'
| 'complete'
| 'error'
| 'tool_start'
| 'tool_end';
content?: string;
phase?: string;
tokens?: number;
tool_id?: string;
tool_name?: string;
tool_input?: string;
tool_raw_input?: string;
tool_output?: string;
tool_success?: boolean;
}
/**
* Optional scope for a manual patrol run.
*
* When resource_ids or resource_types are present, POST /api/ai/patrol/run
* starts a manual Targeted check over the same scoped engine the automatic
* alert path uses, instead of a fleet-wide Patrol check. A scoped run bypasses
* the full-run cadence gate but still honours Patrol readiness.
*/
// Mirrors the backend's manualScopedPatrolRequest exactly: the run endpoint
// decodes with DisallowUnknownFields, so any extra key is a 400.
export interface PatrolRunScope {
resource_ids?: string[];
resource_types?: string[];
alert_identifier?: string;
alert_type?: string;
}
/**
* Trigger a manual patrol run.
*
* Without a scope this starts a fleet-wide Patrol check (the legacy Run
* Patrol behaviour). Pass a scope to run a manual Targeted check scoped to
* specific resources — e.g. a single alert's resource.
*/
export async function triggerPatrolRun(scope?: PatrolRunScope): Promise<{
success: boolean;
accepted?: boolean;
message: string;
run_id?: string;
started_at?: string;
}> {
const hasScope =
!!scope && ((scope.resource_ids?.length ?? 0) > 0 || (scope.resource_types?.length ?? 0) > 0);
return apiFetchJSON('/api/ai/patrol/run', {
method: 'POST',
...(hasScope
? { body: JSON.stringify(scope), headers: { 'Content-Type': 'application/json' } }
: {}),
});
}
/**
* Response shape for POST /api/ai/patrol/preflight.
*
* The preflight runs a one-shot tool-call round-trip against the
* configured (or overridden) Patrol provider+model so operators can
* verify tool calling actually works before relying on the scheduled
* cadence. Distinct from the per-provider /api/ai/test endpoints,
* which only list models.
*
* - success: provider call succeeded AND the model emitted a tool call.
* - tool_call_observed: whether the model emitted a tool call. False
* with success=false means the request failed; false with
* success=false and cause=model_tool_support_unverified means the
* provider accepted the request but the model did not call the tool
* (a soft warning — Patrol may still work in practice).
*/
export interface PatrolPreflightResponse {
success: boolean;
provider?: string;
model?: string;
tool_call_observed: boolean;
duration_ms: number;
message: string;
cause?: string;
summary?: string;
description?: string;
recommendation?: string;
action?: string;
// Wall-clock time when this preflight was recorded by Pulse. Present
// on hydrated cached state from /api/settings/ai; the live POST
// response also returns these fields when populated server-side.
recorded_at?: string;
recorded_at_unix?: number;
}
export interface PatrolPreflightRequest {
provider?: string;
model?: string;
}
/**
* Verify that the configured Patrol provider+model can actually call tools.
*
* Pass `provider` and/or `model` to override the configured Patrol
* selection (useful when previewing a new model before saving).
*/
export async function runPatrolPreflight(
body: PatrolPreflightRequest = {},
): Promise<PatrolPreflightResponse> {
return apiFetchJSON<PatrolPreflightResponse>('/api/ai/patrol/preflight', {
method: 'POST',
body: JSON.stringify(body),
headers: { 'Content-Type': 'application/json' },
});
}
export interface PatrolModelReadinessRequest {
provider?: string;
model?: string;
}
export type PatrolModelReadinessResponse = PatrolModelReadinessSnapshot;
/**
* Run the explicit Patrol model readiness advisor. The request exercises the
* streaming tool path with typed arguments, context fixtures, and a synthetic
* tool-result continuation. Passing an AbortSignal cancels the server-side
* provider request through the HTTP request context.
*/
export async function runPatrolModelReadiness(
body: PatrolModelReadinessRequest = {},
signal?: AbortSignal,
): Promise<PatrolModelReadinessResponse> {
return apiFetchJSON<PatrolModelReadinessResponse>('/api/ai/patrol/readiness', {
method: 'POST',
body: JSON.stringify(body),
headers: { 'Content-Type': 'application/json' },
signal,
});
}
// --- Weekly digest ("what Patrol did for you") ---------------------------
// Mirrors internal/ai/patrol_digest.go. Every number is a rollup over records
// Pulse already keeps; see docs/PATROL_WEEKLY_DIGEST.md for sources and limits.
export type PatrolDigestMode = 'monitor' | 'approval' | 'assisted' | 'full';
export interface PatrolDigestWindow {
start: string;
end: string;
days: number;
history_complete: boolean;
history_since?: string;
}
export interface PatrolDigestRuns {
total: number;
scheduled: number;
event_triggered: number;
manual: number;
failed: number;
checks: number;
resources_covered: number;
last_run_at?: string;
}
export interface PatrolDigestSeverityCounts {
critical: number;
warning: number;
watch: number;
info: number;
}
export interface PatrolDigestFindings {
new: number;
open_by_severity: PatrolDigestSeverityCounts;
resolved: number;
auto_resolved: number;
dismissed: number;
suppressed: number;
}
export interface PatrolDigestInvestigations {
total: number;
by_outcome: Record<string, number>;
}
export interface PatrolDigestActions {
proposed: number;
approved: number;
rejected: number;
executed: number;
verified: number;
failed: number;
pending: number;
}
export interface PatrolDigestAlerts {
reviewed: number;
}
export interface PatrolDigestSpend {
estimated_usd: number;
pricing_known: boolean;
input_tokens: number;
output_tokens: number;
calls: number;
}
export interface PatrolDigest {
generated_at: string;
window: PatrolDigestWindow;
mode: PatrolDigestMode;
runs: PatrolDigestRuns;
findings: PatrolDigestFindings;
investigations: PatrolDigestInvestigations;
actions: PatrolDigestActions;
alerts: PatrolDigestAlerts;
spend: PatrolDigestSpend;
}
export const PATROL_DIGEST_DEFAULT_DAYS = 7;
export async function getPatrolDigest(
days: number = PATROL_DIGEST_DEFAULT_DAYS,
signal?: AbortSignal,
): Promise<PatrolDigest> {
const search = new URLSearchParams({ days: String(days) });
return apiFetchJSON<PatrolDigest>(`/api/ai/patrol/digest?${search.toString()}`, { signal });
}