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.

11.2 KB
Raw Blame
import type {
  ActionAuditOrigin,
  ActionAuditRecord,
  ActionResourceReference,
  ActionAuditState,
  ActionEvidenceClass,
  ActionPolicyAuthorityFactor,
  ActionPolicyReasonCode,
  ActionVerificationTruthStatus,
} from '@/types/actionAudit';
import { buildPatrolAttentionPath, PATROL_PATH } from '@/routing/resourceLinks';
import type { MetadataBadgeTone } from '@/components/shared/MetadataBadge';
import type { UpgradeDestination } from '@/utils/upgradeNavigation';

export const formatActionName = (value: string): string =>
  value === 'install_os_updates'
    ? 'Install operating system updates'
    : value === 'clean_package_cache'
      ? 'Clear downloaded package data'
      : value
          .replace(/[._-]+/g, ' ')
          .trim()
          .replace(/\b\w/g, (letter) => letter.toUpperCase());

const getActionOriginSurface = (origin?: ActionAuditOrigin): string =>
  origin?.surface.trim().toLowerCase() ?? '';

const isPatrolActionOrigin = (surface: string): boolean =>
  surface === 'operational_trust_attention' ||
  surface === 'patrol_control' ||
  surface === 'pulse_patrol' ||
  surface === 'patrol';

export const getActionOriginLabel = (origin?: ActionAuditOrigin): string | undefined => {
  const surface = getActionOriginSurface(origin);
  if (!surface) return undefined;
  if (isPatrolActionOrigin(surface)) return 'From Patrol';
  if (surface === 'pulse_assistant' || surface === 'assistant' || surface === 'chat') {
    return 'From Assistant';
  }
  if (surface === 'mcp' || surface === 'pulse_mcp') return 'From MCP';
  return 'From Pulse';
};

export interface ActionOriginDestination {
  href: string;
  exact: boolean;
}

export const getActionOriginDestination = (
  origin?: ActionAuditOrigin,
): ActionOriginDestination | undefined => {
  if (!isPatrolActionOrigin(getActionOriginSurface(origin))) return undefined;
  const operationalRecordId = origin?.operationalRecordId?.trim();
  return operationalRecordId
    ? { href: buildPatrolAttentionPath(operationalRecordId), exact: true }
    : { href: PATROL_PATH, exact: false };
};

export interface ActionInboxStatePresentation {
  accentClass: string;
  label: string;
  tone: MetadataBadgeTone;
}

const ACTION_INBOX_STATE_PRESENTATION: Record<ActionAuditState, ActionInboxStatePresentation> = {
  planned: { accentClass: 'border-l-slate-400', label: 'Ready to review', tone: 'muted' },
  pending_approval: {
    accentClass: 'border-l-amber-500',
    label: 'Approval required',
    tone: 'warning',
  },
  approved: { accentClass: 'border-l-sky-500', label: 'Ready to run', tone: 'info' },
  executing: { accentClass: 'border-l-blue-500', label: 'Running', tone: 'info' },
  completed: { accentClass: 'border-l-emerald-500', label: 'Completed', tone: 'success' },
  failed: { accentClass: 'border-l-red-500', label: 'Failed', tone: 'danger' },
  rejected: { accentClass: 'border-l-slate-400', label: 'Rejected', tone: 'muted' },
  expired: { accentClass: 'border-l-slate-400', label: 'Expired', tone: 'muted' },
};

export const getActionInboxStatePresentation = (
  state: ActionAuditState,
): ActionInboxStatePresentation => ACTION_INBOX_STATE_PRESENTATION[state];

export const getActionAuditStatePresentation = (
  audit: ActionAuditRecord,
): ActionInboxStatePresentation =>
  audit.state === 'failed' &&
  audit.result?.actionResultV2?.execution.reasonCode === 'operator_force_failed'
    ? { accentClass: 'border-l-amber-500', label: 'Outcome unknown', tone: 'warning' }
    : getActionInboxStatePresentation(audit.state);

const OPEN_ACTION_PRIORITY: Record<ActionAuditState, number> = {
  pending_approval: 0,
  planned: 1,
  approved: 1,
  executing: 2,
  failed: 3,
  completed: 4,
  rejected: 4,
  expired: 4,
};

export const sortOpenActionsForReview = (
  actions: readonly ActionAuditRecord[],
): ActionAuditRecord[] =>
  [...actions].sort((left, right) => {
    const priority = OPEN_ACTION_PRIORITY[left.state] - OPEN_ACTION_PRIORITY[right.state];
    if (priority !== 0) return priority;
    return Date.parse(right.updatedAt) - Date.parse(left.updatedAt);
  });

export interface ActionApprovalBadgePresentation {
  count: number;
  label: string;
}

export const getActionApprovalBadgePresentation = (
  count: number,
): ActionApprovalBadgePresentation | null => {
  if (!Number.isFinite(count) || count <= 0) return null;
  const normalized = Math.floor(count);
  return {
    count: normalized,
    label: `${normalized} ${normalized === 1 ? 'action awaits' : 'actions await'} approval`,
  };
};

export interface ActionsWatchOnlyEmptyStateInput {
  // False while AI is off or unconfigured: Patrol is not running at all, so
  // naming its Watch only mode (or pitching Pro modes) would be untrue.
  aiEnabled: boolean;
  patrolWatchOnly: boolean;
  patrolModesUnlocked: boolean;
  commercialSurfacesHidden: boolean;
  upgradePromptsHidden: boolean;
  upgradeDestination: UpgradeDestination;
}

export type ActionsWatchOnlyEmptyStatePresentation =
  | { kind: 'switch'; body: string; actionLabel: string }
  | { kind: 'upgrade'; body: string; actionLabel?: string; destination?: UpgradeDestination };

// Guidance for the empty Open inbox: while Patrol runs Watch only nothing ever
// lands here, so the calm state has to name the mode that keeps the queue empty
// and point at the dial (or the entitlement) that changes it.
export const getActionsWatchOnlyEmptyState = (
  input: ActionsWatchOnlyEmptyStateInput,
): ActionsWatchOnlyEmptyStatePresentation | undefined => {
  if (!input.aiEnabled || !input.patrolWatchOnly) return undefined;
  if (input.patrolModesUnlocked) {
    return {
      kind: 'switch',
      body: 'Patrol runs in Watch only mode, so it reports issues without preparing fixes. Switch Patrol to Ask first and proposed fixes will wait here for your approval.',
      actionLabel: 'Open Patrol',
    };
  }
  if (input.commercialSurfacesHidden) return undefined;
  const presentation: ActionsWatchOnlyEmptyStatePresentation = {
    kind: 'upgrade',
    body: 'Patrol runs in Watch only mode. Pulse Pro lets Patrol investigate issues and prepare fixes that wait here for your approval.',
  };
  if (!input.upgradePromptsHidden) {
    presentation.actionLabel = 'Learn about Pulse Pro';
    presentation.destination = input.upgradeDestination;
  }
  return presentation;
};

export interface ActionResourcePresentation {
  detail: string;
  label: string;
}

const OPAQUE_RESOURCE_SUFFIX = /^(?:[a-f\d]{12,}|[a-z\d]{16,})$/i;

const compactOpaqueSuffix = (value: string): string => `…${value.slice(-6)}`;

const DASHED_RESOURCE_PREFIXES: Array<{ prefix: string; label: string }> = [
  { prefix: 'app-container', label: 'App container' },
  { prefix: 'agent', label: 'Host agent' },
  { prefix: 'vm', label: 'Virtual machine' },
];

const CANONICAL_RESOURCE_KINDS: Record<string, string> = {
  'docker:container': 'Docker container',
  'proxmox:node': 'Proxmox node',
  'proxmox:vm': 'Proxmox virtual machine',
  'proxmox:lxc': 'Proxmox container',
};

const RESOURCE_TYPE_LABELS: Record<string, string> = {
  'app-container': 'App container',
  agent: 'Host agent',
  container: 'Container',
  lxc: 'Proxmox container',
  node: 'Node',
  vm: 'Virtual machine',
};

const resourceTypeLabel = (resourceType: string): string =>
  RESOURCE_TYPE_LABELS[resourceType.trim().toLowerCase()] || formatActionName(resourceType);

export const getActionResourcePresentation = (
  resourceId: string,
  resource?: ActionResourceReference,
): ActionResourcePresentation => {
  const normalized = resourceId.trim();
  if (!normalized) return { label: 'Unknown resource', detail: '' };

  const authoritativeName = resource?.name?.trim();
  if (authoritativeName) {
    return {
      label: authoritativeName,
      detail: resourceTypeLabel(resource?.type ?? ''),
    };
  }

  const canonicalParts = normalized.split(':').filter(Boolean);
  if (canonicalParts.length > 1) {
    const name = canonicalParts.at(-1) || normalized;
    const kindKey = canonicalParts.slice(0, -1).join(':').toLowerCase();
    const kind = CANONICAL_RESOURCE_KINDS[kindKey] || formatActionName(kindKey);
    return OPAQUE_RESOURCE_SUFFIX.test(name)
      ? { label: kind, detail: compactOpaqueSuffix(name) }
      : { label: name, detail: kind };
  }

  for (const candidate of DASHED_RESOURCE_PREFIXES) {
    const prefix = `${candidate.prefix}-`;
    if (!normalized.toLowerCase().startsWith(prefix)) continue;
    const suffix = normalized.slice(prefix.length);
    return {
      label: candidate.label,
      detail: OPAQUE_RESOURCE_SUFFIX.test(suffix) ? compactOpaqueSuffix(suffix) : suffix,
    };
  }

  return { label: normalized, detail: '' };
};

export const formatPolicyAuthority = (factor: ActionPolicyAuthorityFactor): string => {
  switch (factor.kind) {
    case 'capability_registry':
      return 'Capability safety policy';
    case 'tenant_patrol_policy':
      return 'Patrol policy for this organization';
    case 'resource_operator_policy':
      return 'Policy for this resource';
  }
};

const POLICY_REASON_LABELS: Record<ActionPolicyReasonCode, string> = {
  capability_approval_none: 'No approval floor',
  capability_approval_admin: 'Administrator approval required',
  capability_approval_mfa: 'Verified approval required',
  capability_dry_run_only: 'Dry run only',
  capability_auto_never: 'Automatic execution not allowed',
  capability_auto_low_risk: 'Eligible for low-risk automation',
  capability_auto_elevated: 'Eligible for elevated automation',
  tenant_policy_unavailable: 'Organization policy unavailable',
  tenant_emergency_stop: 'Emergency stop is active',
  tenant_mode_monitor: 'Patrol is in Watch only',
  tenant_mode_assisted: 'Patrol is in Safe fixes',
  tenant_mode_full: 'Patrol is in Autopilot',
  tenant_mode_unknown: 'Patrol mode is unknown',
  tenant_full_mode_locked: 'Autopilot acknowledgement is not active',
  tenant_full_mode_unlocked: 'Autopilot acknowledgement is active',
  resource_policy_unavailable: 'Resource policy unavailable',
  resource_policy_missing: 'No resource policy is recorded',
  resource_never_auto_remediate: 'Automatic remediation is blocked for this resource',
  resource_capability_allowed: 'This action is allowed for the resource',
  resource_capability_not_allowed: 'This action is not allowed for the resource',
  resource_window_open: 'Resource action window is open',
  resource_window_closed: 'Resource action window is closed',
};

export const formatPolicyReason = (reason: ActionPolicyReasonCode): string =>
  POLICY_REASON_LABELS[reason];

export const formatEvidenceClass = (value: ActionEvidenceClass): string => {
  switch (value) {
    case 'independent':
      return 'Independent observer';
    case 'agent_attested':
      return 'Executing agent';
    case 'none':
      return 'No evidence source';
  }
};

export const verificationTruthLabel = (
  status: ActionVerificationTruthStatus,
  evidenceClass?: ActionEvidenceClass,
): string => {
  switch (status) {
    case 'confirmed':
      return evidenceClass === 'independent'
        ? 'Confirmed by independent observer'
        : evidenceClass === 'agent_attested'
          ? 'Confirmed by executing agent'
          : 'Confirmation lacks an evidence source';
    case 'contradicted':
      return 'Outcome contradicted';
    case 'inconclusive':
      return 'Outcome inconclusive';
    case 'not_attempted':
      return 'Outcome not verified';
  }
};