@oneuptime/common 13.0.5 → 13.0.7

package/Server/Utils/AI/Chat/ChatAgentRunner.ts

@@ -9,7 +9,10 @@ import { JSONObject } from "../../../../Types/JSON";
 import ObjectID from "../../../../Types/ObjectID";
 import AIChatMessageRole from "../../../../Types/AI/AIChatMessageRole";
 import AIChatMessageStatus from "../../../../Types/AI/AIChatMessageStatus";
-import { AIChatPageContext } from "../../../../Types/AI/AIChatPageContext";
+import {
+  AIChatPageContext,
+  AIChatPageContextHelper,
+} from "../../../../Types/AI/AIChatPageContext";
 import AIChatPermissionMode from "../../../../Types/AI/AIChatPermissionMode";
 import AIRunEventType from "../../../../Types/AI/AIRunEventType";
 import AIRunStatus from "../../../../Types/AI/AIRunStatus";
@@ -54,9 +57,10 @@ export interface ChatTurnRequest {
    * subject; later turns that arrive without a page context (the user
    * navigated away mid-conversation) fall back to that persisted subject so
    * "this incident" keeps resolving. Not needed on resume (the paused state
-   * already contains the built prompt).
+   * already contains the built prompt). Explicit null detaches the page and
+   * clears that persisted subject.
    */
-  pageContext?: AIChatPageContext | undefined;
+  pageContext?: AIChatPageContext | null | undefined;
   // The requesting user's real permission props, captured at request time.
   props: DatabaseCommonInteractionProps;
 }
@@ -1377,6 +1381,15 @@ export default class ChatAgentRunner {
     request: ChatTurnRequest,
   ): Promise<AIChatPageContext | undefined> {
     try {
+      if (request.pageContext === null) {
+        await AIConversationService.updateOneById({
+          id: request.conversationId,
+          data: { pageContext: null } as never,
+          props: { isRoot: true },
+        });
+        return undefined;
+      }
+
       const conversation: AIConversation | null =
         await AIConversationService.findOneById({
           id: request.conversationId,
@@ -1400,11 +1413,11 @@ export default class ChatAgentRunner {
        * stale first subject would silently flip the conversation back.
        */
       const persistedSignature: string = persisted
-        ? `${persisted.type}:${persisted.entityId || ""}`
+        ? AIChatPageContextHelper.getIdentity(persisted)
         : "";
-      const incomingSignature: string = `${request.pageContext.type}:${
-        request.pageContext.entityId || ""
-      }`;
+      const incomingSignature: string = AIChatPageContextHelper.getIdentity(
+        request.pageContext,
+      );
 
       if (persistedSignature !== incomingSignature) {
         await AIConversationService.updateOneById({
@@ -1423,7 +1436,7 @@ export default class ChatAgentRunner {
           error instanceof Error ? error.message : String(error)
         }`,
       );
-      return request.pageContext;
+      return request.pageContext || undefined;
     }
   }
 

package/Server/Utils/AI/Chat/ObservabilityChatPrompt.ts

@@ -2,6 +2,10 @@ import AIChatPageContextType, {
   AIChatPageContext,
 } from "../../../../Types/AI/AIChatPageContext";
 import AIChatPermissionMode from "../../../../Types/AI/AIChatPermissionMode";
+import {
+  getAIResourceDefinition,
+  isAIResourceType,
+} from "../../../../Types/AI/AIResourceContext";
 
 /*
  * System prompt for the observability chat agent. The binding rules here
@@ -42,6 +46,8 @@ function buildEntityContextGuidance(context: AIChatPageContext): string {
     : "";
 
   switch (context.type) {
+    case AIChatPageContextType.Resource:
+      return buildResourceContextGuidance(context);
     case AIChatPageContextType.Incident:
       return `an incident${titlePart}. Fetch its full details with query_incidents using incidentId="${id}" before answering questions about it. An autonomous AI investigation may already exist for this incident — call get_ai_investigation first and build on (and cite) its findings rather than re-deriving them from raw telemetry. get_incident_timeline is how to answer "what's the latest": it returns the incident's state changes, notes and notifications in order. Incident actions (acknowledge_incident, resolve_incident, post_incident_status_update, change_incident_severity, page_on_call_policy, run_runbook) take this same incidentId. Use the incident's start time and affected monitors to scope log, trace and metric queries when investigating it.`;
     case AIChatPageContextType.Alert:
@@ -52,6 +58,8 @@ function buildEntityContextGuidance(context: AIChatPageContext): string {
       return `a scheduled maintenance event${titlePart}. Fetch its full details with query_scheduled_maintenance using scheduledMaintenanceId="${id}" — including its window (startsAt/endsAt) and affected monitors. Use that window to scope log, trace and metric queries, and to judge whether telemetry changes during it were expected maintenance rather than a real problem.`;
     case AIChatPageContextType.TelemetryService:
       return `a telemetry service${titlePart}. Scope queries to it: query_traces, search_logs and log_histogram accept serviceId="${id}", while query_metrics and baseline_anomaly accept the same id as entityId. Use lookup_context to discover this service's metric names.`;
+    case AIChatPageContextType.RumApplication:
+      return `a Real User Monitoring application${titlePart}. Fetch its name and connection health with query_rum_applications using rumApplicationId="${id}". Use query_rum_web_vitals with the same rumApplicationId to compare LCP, INP, CLS, FCP and TTFB in an explicit time window against the preceding equal-length window. It returns measured averages, units, ratings and changes; missing measurements are not zero. For a trend chart, use the returned metric name with query_metrics and entityId="${id}". For slow browser operations or error spans, use query_traces with serviceId="${id}" and metric="p95Duration" or metric="errorCount", grouped by name. Span counts are not page views or unique users. These tools do not read session recordings. Report observed regressions and distinguish them from statistically established anomalies; do not infer a root cause from a change alone.`;
     case AIChatPageContextType.Trace:
       return `a distributed trace. Fetch its span tree with get_trace using traceId="${id}", and its logs with search_logs using the same traceId.`;
     case AIChatPageContextType.Exception:
@@ -72,8 +80,10 @@ function buildEntityContextGuidance(context: AIChatPageContext): string {
  * "which incidents are currently active or unresolved?". Every affordance an
  * area page's suggested prompts depend on has to be named here.
  */
-function buildAreaContextGuidance(type: AIChatPageContextType): string {
-  switch (type) {
+function buildAreaContextGuidance(context: AIChatPageContext): string {
+  switch (context.type) {
+    case AIChatPageContextType.ResourcesList:
+      return buildResourceContextGuidance(context);
     case AIChatPageContextType.IncidentsList:
       return `the incidents list. Questions about "these incidents" or incident activity are answered with query_incidents: pass state="active" to list every incident that is unresolved RIGHT NOW (this drops the time window, so incidents opened weeks ago are still returned), leave state unset for recent activity in a window, or pass incidentId for one incident's full details. search_incidents does free-text search over past incidents.`;
     case AIChatPageContextType.AlertsList:
@@ -90,11 +100,36 @@ function buildAreaContextGuidance(type: AIChatPageContextType): string {
       return `the metrics explorer. Discover metric names with lookup_context, then chart them with query_metrics; baseline_anomaly checks a metric against its learned baseline.`;
     case AIChatPageContextType.ExceptionsList:
       return `the exceptions list. Questions about exceptions are answered with top_exceptions; find_code_for_exception maps one to source code.`;
+    case AIChatPageContextType.RumApplications:
+      return `the Real User Monitoring applications list. Discover application ids, names and connection health with query_rum_applications before querying their data. Use query_rum_web_vitals with a rumApplicationId to compare web-vital averages and ratings against the preceding equal-length window. It returns the exact metric names to chart with query_metrics using entityId. query_traces accepts an application's id as serviceId for slow browser operations and error spans. Scope every query to the selected application and state the time window and any missing measurements. Span counts are not page views or unique users, and these tools do not read session recordings.`;
+    case AIChatPageContextType.TelemetryServicesList:
+      return `the telemetry services list. Discover services with lookup_context using type="services", then scope query_traces, search_logs and log_histogram with serviceId. Compare latency and error counts with query_traces grouped by primaryEntityId; discover metrics with lookup_context before calling query_metrics or baseline_anomaly with entityId.`;
     default:
       return "";
   }
 }
 
+function buildResourceContextGuidance(context: AIChatPageContext): string {
+  if (!isAIResourceType(context.resourceType)) {
+    return "";
+  }
+  const label: string = getAIResourceDefinition(context.resourceType).label;
+  const pluralLabel: string = getAIResourceDefinition(
+    context.resourceType,
+  ).pluralLabel;
+  const resourceArgs: string = JSON.stringify({
+    resourceType: context.resourceType,
+    ...(context.entityId ? { resourceId: context.entityId } : {}),
+  });
+  const subject: string = context.entityId
+    ? `a ${label}${context.entityTitle ? ` titled ${JSON.stringify(context.entityTitle)}` : ""}`
+    : `the ${pluralLabel} list`;
+  const childGuidance: string = context.subresource
+    ? ` The selected child or collection is ${JSON.stringify(context.subresource)}. Child names are UI hints, not verified unique identities: Kubernetes names may exist in multiple namespaces, container names may be reused and process IDs may be recycled. Do not invent a namespace or child ID. The resource telemetry tool returns the parent resource's data; explicitly state that scope and never describe it as child-only measurements. If the question needs child-specific evidence that the tools cannot retrieve, explain that limitation.`
+    : "";
+  return `${subject}. Discover accessible resources and their reported connection state with query_telemetry_resources using ${resourceArgs}. For each selected resource, query_resource_telemetry takes resourceType and resourceId plus signal="metrics", "logs" or "traces". For metrics, omit metricName first to discover metric names within that resource, then pass an observed name and mode="trend" for a chart or mode="summary" for a range aggregate. Logs return a severity histogram; traces return operation summaries. Use explicit time windows and cite measured results. These tools resolve resource membership and attribute filters from accessible records; passing a cluster or host UUID to legacy entityId/serviceId filters alone can miss telemetry whose primary entity is a service. Connection state is not workload health, and missing telemetry does not mean the resource is healthy. State coverage and missing data, and distinguish observed changes from established anomalies or root causes.${childGuidance}`;
+}
+
 export function buildPageContextSection(
   context: AIChatPageContext | undefined,
 ): string {
@@ -106,7 +141,7 @@ export function buildPageContextSection(
 
   const guidance: string = isEntity
     ? buildEntityContextGuidance(context)
-    : buildAreaContextGuidance(context.type);
+    : buildAreaContextGuidance(context);
 
   if (!guidance) {
     return "";
@@ -132,7 +167,7 @@ export function buildObservabilityChatSystemPrompt(data: {
   permissionMode: AIChatPermissionMode;
   pageContext?: AIChatPageContext | undefined;
 }): string {
-  return `You are OneUptime's observability copilot: a careful SRE analyst that answers questions about — and can take action on — this project's traces, metrics, logs, exceptions, incidents, monitors, alerts and scheduled maintenance, the on-call, status page, SLO and runbook platform around them, and the source code in its connected code repositories.
+  return `You are OneUptime's observability copilot: a careful SRE analyst that answers questions about — and can take action on — this project's traces, metrics, logs, exceptions, incidents, monitors, alerts and scheduled maintenance, Real User Monitoring applications and web vitals, the on-call, status page, SLO and runbook platform around them, and the source code in its connected code repositories.
 
 The current time is ${data.currentTime.toISOString()}.${buildPageContextSection(
     data.pageContext,
@@ -149,6 +184,8 @@ ${buildActionGuidance(data.permissionMode)}
 ## How to investigate
 
 - Resolve names first: use lookup_context to turn a service name into its ID before filtering other tools by service, and to discover metric names.
+- For infrastructure (hosts, Docker, Podman, Kubernetes, Docker Swarm, Proxmox, VMware, Ceph, serverless, cloud, IoT and network devices), discover resources with query_telemetry_resources and use query_resource_telemetry for their scoped metric trends, log severity and trace operations. Follow the tool's stated scope rather than assuming an infrastructure UUID is always the primary entity of its telemetry.
+- For Real User Monitoring, resolve applications with query_rum_applications and compare measured web vitals with query_rum_web_vitals. Use returned metric names with query_metrics to chart trends. Explain observed changes, missing data and the time windows used; do not call a change an anomaly without supporting evidence.
 - Prefer aggregations (query_traces, log_histogram, query_metrics, top_exceptions, security_event_summary) to establish the shape of a problem, then drill into raw data (search_logs, get_trace, search_security_events) for evidence.
 - Always pass explicit ISO 8601 time ranges. If the user did not specify one, use the last hour for logs and the last 24 hours for metrics/traces, and say which window you used.
 - When durations are involved they are in milliseconds unless stated otherwise.

package/Server/Utils/AI/CodeFix/CodeAgentWorkspaceGuard.ts

@@ -3,7 +3,7 @@ import path from "path";
 
 /*
  * Pure guards for the in-house code agent's workspace tools (B4 Tier 0,
- * Internal/Roadmap/CodeFixSandboxDesign.md): every file-system tool call is
+ * Docs/Internal/Roadmap/CodeFixSandboxDesign.md): every file-system tool call is
  * path-guarded to the run's ephemeral workspace (the same escape posture as
  * WorkspaceManager.deleteWorkspace's base-directory check), and every tool
  * output is truncated before it re-enters the model context. Kept pure —

package/Server/Utils/AI/CodeFix/CodeFixAgentCompletion.ts

@@ -23,7 +23,7 @@ import CaptureSpan from "../../Telemetry/CaptureSpan";
 
 /*
  * Server-mediated LLM completions for the in-house code-fix agent (B4 Tier
- * 0, Internal/Roadmap/CodeFixSandboxDesign.md). The worker never holds a
+ * 0, Docs/Internal/Roadmap/CodeFixSandboxDesign.md). The worker never holds a
  * provider secret: every completion of its tool loop is executed HERE via
  * AIService.executeWithLogging — logged to LlmLog, linked to the run, billed
  * when the provider is the costed global one, and inside the G4 daily

package/Server/Utils/AI/IncidentAIContextBuilder.ts

@@ -62,6 +62,9 @@ export default class IncidentAIContextBuilder {
         monitors: {
           name: true,
         },
+        serviceLevelObjectives: {
+          name: true,
+        },
         labels: {
           name: true,
           color: true,
@@ -241,6 +244,24 @@ export default class IncidentAIContextBuilder {
       contextText += "\n\n";
     }
 
+    /*
+     * Affected SLOs. A burn-rate incident has no monitors, so without this
+     * the model would see an incident about nothing in particular.
+     */
+    const affectedSloNames: Array<string> = (
+      incident.serviceLevelObjectives || []
+    )
+      .map((slo: { name?: string | undefined }): string => {
+        return slo.name || "";
+      })
+      .filter((name: string): boolean => {
+        return name.length > 0;
+      });
+
+    if (affectedSloNames.length > 0) {
+      contextText += `**Affected SLOs:** ${affectedSloNames.join(", ")}\n\n`;
+    }
+
     // Labels
     if (incident.labels && incident.labels.length > 0) {
       contextText += "**Labels:** ";
@@ -432,6 +453,24 @@ Grounding rules (important):
       contextText += "\n\n";
     }
 
+    /*
+     * Affected SLOs. A burn-rate incident has no monitors, so without this
+     * the model would see an incident about nothing in particular.
+     */
+    const affectedSloNames: Array<string> = (
+      incident.serviceLevelObjectives || []
+    )
+      .map((slo: { name?: string | undefined }): string => {
+        return slo.name || "";
+      })
+      .filter((name: string): boolean => {
+        return name.length > 0;
+      });
+
+    if (affectedSloNames.length > 0) {
+      contextText += `**Affected SLOs:** ${affectedSloNames.join(", ")}\n\n`;
+    }
+
     // Labels
     if (incident.labels && incident.labels.length > 0) {
       contextText += "**Labels:** ";

package/Server/Utils/AI/SRE/AIInvestigationEngine.ts

@@ -1,3 +1,4 @@
+import { InvestigationNotStartedCode } from "../../../../Types/AI/InvestigationNotStartedReason";
 import ObjectID from "../../../../Types/ObjectID";
 import OneUptimeDate from "../../../../Types/Date";
 import { JSONObject } from "../../../../Types/JSON";
@@ -186,6 +187,13 @@ export default class AIInvestigationEngine {
     projectId: ObjectID,
     subjectType: AISubjectType,
   ): Promise<boolean> {
+    return (await this.getDisabledReason(projectId, subjectType)) === null;
+  }
+
+  public static async getDisabledReason(
+    projectId: ObjectID,
+    subjectType: AISubjectType,
+  ): Promise<InvestigationNotStartedCode | null> {
     const project: Project | null = await ProjectService.findOneById({
       id: projectId,
       select: {
@@ -197,11 +205,11 @@ export default class AIInvestigationEngine {
     });
 
     if (!project) {
-      return false;
+      return "eligibility_check_failed";
     }
 
     if (project.enableAi === false) {
-      return false;
+      return "ai_disabled";
     }
 
     const isOptedIn: boolean =
@@ -210,7 +218,7 @@ export default class AIInvestigationEngine {
         : project.enableAutomaticIncidentInvestigation === true;
 
     if (!isOptedIn) {
-      return false;
+      return "automatic_investigation_disabled";
     }
 
     const llmProvider: LlmProvider | null =
@@ -220,10 +228,10 @@ export default class AIInvestigationEngine {
       logger.debug(
         `AI: skipping investigation for project ${projectId.toString()} — no LLM provider configured.`,
       );
-      return false;
+      return "provider_missing";
     }
 
-    return true;
+    return null;
   }
 
   /*

package/Server/Utils/AI/SRE/AlertInvestigationRunner.ts

@@ -1,3 +1,8 @@
+import {
+  InvestigationNotStartedCode,
+  InvestigationGateDetails,
+} from "../../../../Types/AI/InvestigationNotStartedReason";
+import InvestigationEligibility from "./InvestigationEligibility";
 import ObjectID from "../../../../Types/ObjectID";
 import OneUptimeDate from "../../../../Types/Date";
 import SortOrder from "../../../../Types/BaseDatabase/SortOrder";
@@ -16,7 +21,10 @@ import QueryHelper from "../../../Types/Database/QueryHelper";
 import AlertAIContextBuilder, {
   AlertContextData,
 } from "../AlertAIContextBuilder";
-import { AI_ALERT_INVESTIGATION_FEATURE } from "../../../Services/AIService";
+import {
+  AI_ALERT_INVESTIGATION_FEATURE,
+  AutonomousBudgetStatus,
+} from "../../../Services/AIService";
 import AIInvestigationEngine from "./AIInvestigationEngine";
 import AIInvestigationQueue from "./InvestigationQueue";
 import AIConfidenceSignal, { ConfidenceSignal } from "./ConfidenceSignal";
@@ -51,6 +59,8 @@ const MAX_DEDUPE_WINDOW_MINUTES: number = 24 * 60;
 
 export interface AlertGateDecision {
   investigate: boolean;
+  notStartedCode?: InvestigationNotStartedCode | undefined;
+  notStartedDetails?: InvestigationGateDetails | undefined;
   // Human-readable reason recorded in the debug log when skipping.
   reason: string;
   // Passed through to the AIRun as the dedupe key for future windows.
@@ -77,9 +87,10 @@ export default class AIAlertInvestigationRunner {
     const { alertId, projectId } = data;
 
     try {
-      if (
-        !(await AIInvestigationEngine.isEnabledForProject(projectId, "Alert"))
-      ) {
+      const disabled: InvestigationNotStartedCode | null =
+        await AIInvestigationEngine.getDisabledReason(projectId, "Alert");
+      if (disabled) {
+        await InvestigationEligibility.recordSkipped(data, disabled);
         return false;
       }
 
@@ -89,6 +100,12 @@ export default class AIAlertInvestigationRunner {
       });
 
       if (!gate.investigate) {
+        await InvestigationEligibility.recordSkipped(
+          data,
+          gate.notStartedCode || "eligibility_check_failed",
+          undefined,
+          gate.notStartedDetails,
+        );
         logger.debug(
           `AI: skipping investigation for alert ${alertId.toString()} — ${gate.reason}.`,
         );
@@ -100,11 +117,21 @@ export default class AIAlertInvestigationRunner {
           projectId,
           subjectAlertId: alertId,
           subjectMonitorId: gate.monitorId,
+          onNotEnqueued: async (
+            code: InvestigationNotStartedCode,
+            budget?: AutonomousBudgetStatus,
+          ): Promise<void> => {
+            await InvestigationEligibility.recordSkipped(data, code, budget);
+          },
         },
       );
 
       return enqueuedRunId !== null;
     } catch (error) {
+      await InvestigationEligibility.recordSkipped(
+        data,
+        "eligibility_check_failed",
+      );
       logger.error(
         `AI: unexpected error enqueueing investigation for alert ${alertId.toString()}: ${error}`,
       );
@@ -276,13 +303,18 @@ export default class AIAlertInvestigationRunner {
         monitorId: true,
         alertSeverity: {
           order: true,
+          name: true,
         },
       },
       props: { isRoot: true },
     });
 
     if (!alert) {
-      return { investigate: false, reason: "alert not found" };
+      return {
+        investigate: false,
+        reason: "alert not found",
+        notStartedCode: "eligibility_check_failed",
+      };
     }
 
     // One project read serves both the severity floor and the dedupe window.
@@ -296,19 +328,25 @@ export default class AIAlertInvestigationRunner {
     });
 
     // Severity floor.
-    const floorOrder: number | null = await this.getSeverityFloorOrder(
+    const floorSeverity: AlertSeverity | null = await this.getSeverityFloor(
       projectId,
       project?.alertInvestigationMinimumSeverityId,
     );
+    const floorOrder: number | undefined = floorSeverity?.order;
     const alertOrder: number | undefined = alert.alertSeverity?.order;
 
     if (
-      floorOrder !== null &&
+      floorOrder !== undefined &&
       alertOrder !== undefined &&
       alertOrder > floorOrder
     ) {
       return {
         investigate: false,
+        notStartedCode: "severity_below_threshold",
+        notStartedDetails: {
+          severityName: alert.alertSeverity?.name,
+          minimumSeverityName: floorSeverity?.name,
+        },
         reason: `severity order ${alertOrder} is below the investigation floor (order ${floorOrder})`,
         monitorId: alert.monitorId,
       };
@@ -349,6 +387,8 @@ export default class AIAlertInvestigationRunner {
       if (recentRunCount > 0) {
         return {
           investigate: false,
+          notStartedCode: "monitor_cooldown",
+          notStartedDetails: { cooldownWindowMinutes: dedupeWindowMinutes },
           reason: `monitor ${alert.monitorId.toString()} was already investigated within the last ${dedupeWindowMinutes} minutes`,
           monitorId: alert.monitorId,
         };
@@ -369,27 +409,27 @@ export default class AIAlertInvestigationRunner {
    * configured severity has been deleted — the default is the project's top
    * two tiers. Returns null when no floor applies (no severities configured).
    */
-  private static async getSeverityFloorOrder(
+  private static async getSeverityFloor(
     projectId: ObjectID,
     minimumSeverityId: ObjectID | undefined,
-  ): Promise<number | null> {
+  ): Promise<AlertSeverity | null> {
     if (minimumSeverityId) {
       const floorSeverity: AlertSeverity | null =
         await AlertSeverityService.findOneById({
           id: minimumSeverityId,
-          select: { order: true },
+          select: { order: true, name: true },
           props: { isRoot: true },
         });
 
       if (floorSeverity && floorSeverity.order !== undefined) {
-        return floorSeverity.order;
+        return floorSeverity;
       }
     }
 
     // Default: the top two severity tiers (the two lowest order values).
     const topTiers: Array<AlertSeverity> = await AlertSeverityService.findBy({
       query: { projectId },
-      select: { order: true },
+      select: { order: true, name: true },
       sort: { order: SortOrder.Ascending },
       limit: 2,
       skip: 0,
@@ -401,7 +441,7 @@ export default class AIAlertInvestigationRunner {
     }
 
     const lastTier: AlertSeverity = topTiers[topTiers.length - 1]!;
-    return lastTier.order ?? null;
+    return lastTier.order !== undefined ? lastTier : null;
   }
 
   // Build a compact alert record to seed the investigation.

package/Server/Utils/AI/SRE/IncidentInvestigationRunner.ts

@@ -1,3 +1,8 @@
+import {
+  InvestigationNotStartedCode,
+  InvestigationGateDetails,
+} from "../../../../Types/AI/InvestigationNotStartedReason";
+import InvestigationEligibility from "./InvestigationEligibility";
 import ObjectID from "../../../../Types/ObjectID";
 import OneUptimeDate from "../../../../Types/Date";
 import AIRunType from "../../../../Types/AI/AIRunType";
@@ -17,7 +22,10 @@ import IncidentService from "../../../Services/IncidentService";
 import IncidentAIContextBuilder, {
   IncidentContextData,
 } from "../IncidentAIContextBuilder";
-import { AI_INCIDENT_INVESTIGATION_FEATURE } from "../../../Services/AIService";
+import {
+  AI_INCIDENT_INVESTIGATION_FEATURE,
+  AutonomousBudgetStatus,
+} from "../../../Services/AIService";
 import AIInvestigationEngine from "./AIInvestigationEngine";
 import AIInvestigationQueue from "./InvestigationQueue";
 import AIConfidenceSignal, { ConfidenceSignal } from "./ConfidenceSignal";
@@ -50,6 +58,8 @@ const MAX_INCIDENT_DEDUPE_WINDOW_MINUTES: number = 24 * 60;
 
 export interface IncidentGateDecision {
   investigate: boolean;
+  notStartedCode?: InvestigationNotStartedCode | undefined;
+  notStartedDetails?: InvestigationGateDetails | undefined;
   reason: string;
   monitorId?: ObjectID | undefined;
 }
@@ -74,12 +84,10 @@ export default class AIIncidentInvestigationRunner {
     const { incidentId, projectId } = data;
 
     try {
-      if (
-        !(await AIInvestigationEngine.isEnabledForProject(
-          projectId,
-          "Incident",
-        ))
-      ) {
+      const disabled: InvestigationNotStartedCode | null =
+        await AIInvestigationEngine.getDisabledReason(projectId, "Incident");
+      if (disabled) {
+        await InvestigationEligibility.recordSkipped(data, disabled);
         return false;
       }
 
@@ -89,6 +97,12 @@ export default class AIIncidentInvestigationRunner {
       });
 
       if (!gate.investigate) {
+        await InvestigationEligibility.recordSkipped(
+          data,
+          gate.notStartedCode || "eligibility_check_failed",
+          undefined,
+          gate.notStartedDetails,
+        );
         logger.debug(
           `AI: skipping investigation for incident ${incidentId.toString()} — ${gate.reason}.`,
         );
@@ -100,11 +114,21 @@ export default class AIIncidentInvestigationRunner {
           projectId,
           subjectIncidentId: incidentId,
           subjectMonitorId: gate.monitorId,
+          onNotEnqueued: async (
+            code: InvestigationNotStartedCode,
+            budget?: AutonomousBudgetStatus,
+          ): Promise<void> => {
+            await InvestigationEligibility.recordSkipped(data, code, budget);
+          },
         },
       );
 
       return enqueuedRunId !== null;
     } catch (error) {
+      await InvestigationEligibility.recordSkipped(
+        data,
+        "eligibility_check_failed",
+      );
       logger.error(
         `AI: unexpected error enqueueing investigation for incident ${incidentId.toString()}: ${error}`,
       );
@@ -140,13 +164,18 @@ export default class AIIncidentInvestigationRunner {
         },
         incidentSeverity: {
           order: true,
+          name: true,
         },
       },
       props: { isRoot: true },
     });
 
     if (!incident) {
-      return { investigate: false, reason: "incident not found" };
+      return {
+        investigate: false,
+        reason: "incident not found",
+        notStartedCode: "eligibility_check_failed",
+      };
     }
 
     const monitorIds: Array<ObjectID> = (incident.monitors || [])
@@ -175,18 +204,24 @@ export default class AIIncidentInvestigationRunner {
      * whose severity order cannot be determined passes, as does every
      * incident when no floor is configured.
      */
-    const floorOrder: number | null = await this.getSeverityFloorOrder(
+    const floorSeverity: IncidentSeverity | null = await this.getSeverityFloor(
       project?.incidentInvestigationMinimumSeverityId,
     );
+    const floorOrder: number | undefined = floorSeverity?.order;
     const incidentOrder: number | undefined = incident.incidentSeverity?.order;
 
     if (
-      floorOrder !== null &&
+      floorOrder !== undefined &&
       incidentOrder !== undefined &&
       incidentOrder > floorOrder
     ) {
       return {
         investigate: false,
+        notStartedCode: "severity_below_threshold",
+        notStartedDetails: {
+          severityName: incident.incidentSeverity?.name,
+          minimumSeverityName: floorSeverity?.name,
+        },
         reason: `severity order ${incidentOrder} is below the investigation floor (order ${floorOrder})`,
         monitorId: primaryMonitorId,
       };
@@ -227,6 +262,8 @@ export default class AIIncidentInvestigationRunner {
       if (recentRunCount > 0) {
         return {
           investigate: false,
+          notStartedCode: "monitor_cooldown",
+          notStartedDetails: { cooldownWindowMinutes: dedupeWindowMinutes },
           reason: `a monitor affected by this incident was already investigated within the last ${dedupeWindowMinutes} minutes`,
           monitorId: primaryMonitorId,
         };
@@ -246,9 +283,9 @@ export default class AIIncidentInvestigationRunner {
    * Returns null when no floor applies — which, unlike the alert lane, is the
    * default: no configured minimum means investigate everything.
    */
-  private static async getSeverityFloorOrder(
+  private static async getSeverityFloor(
     minimumSeverityId: ObjectID | undefined,
-  ): Promise<number | null> {
+  ): Promise<IncidentSeverity | null> {
     if (!minimumSeverityId) {
       return null;
     }
@@ -256,7 +293,7 @@ export default class AIIncidentInvestigationRunner {
     const floorSeverity: IncidentSeverity | null =
       await IncidentSeverityService.findOneById({
         id: minimumSeverityId,
-        select: { order: true },
+        select: { order: true, name: true },
         props: { isRoot: true },
       });
 
@@ -268,7 +305,7 @@ export default class AIIncidentInvestigationRunner {
       return null;
     }
 
-    return floorSeverity.order;
+    return floorSeverity;
   }
 
   /*