Skip to content

armgit / Pulse

Public Imported from GitHub
0

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.

37.9 KB
Raw Blame
/**
 * 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 });
}