@oneuptime/common 13.0.6 → 13.0.7

package/Server/Static/Brand/README.md

@@ -15,26 +15,26 @@ browser drew a broken image. See
 https://github.com/OneUptime/oneuptime/issues/3457.
 
 Every service mounts this directory read-only at `/oneuptime-assets/brand` (see
-`Common/Server/Utils/VendorAssets.ts`). Reference the files from a view by that
+`packages/Common/Server/Utils/VendorAssets.ts`). Reference the files from a view by that
 absolute path, or from server code via the `OneUptimeLogoUrl` constant -
-`Common/Tests/Server/Utils/OfflineAssetHygiene.test.ts` fails the build on a
+`packages/Common/Tests/Server/Utils/OfflineAssetHygiene.test.ts` fails the build on a
 `/oneuptime-assets/...` URL that does not resolve to a file on disk.
 
 ## Contents
 
 | Path                      | Source                                                  |
 | ------------------------- | ------------------------------------------------------- |
-| `oneuptime-logo.svg`      | `Common/UI/Images/logos/OneUptimeSVG/3-transparent.svg` |
-| `ou-wb.svg`, `hou-wb.svg` | `Home/Static/img/`                                      |
-| `favicons/`               | `Home/Static/img/favicons/`                             |
+| `oneuptime-logo.svg`      | `packages/Common/UI/Images/logos/OneUptimeSVG/3-transparent.svg` |
+| `ou-wb.svg`, `hou-wb.svg` | `packages/Home/Static/img/`                                      |
+| `favicons/`               | `packages/Home/Static/img/favicons/`                             |
 
 `favicons/oneuptime-up-v1.svg` is the cache-versioned browser-tab icon shared
 by the Dashboard, Admin Dashboard, and Home page. It keeps the white `Up.` mark
 on its own dark background so the lettering remains visible in both light and
 dark browser chrome.
 
-`Common/Tests/Server/Utils/VendorAssets.test.ts` asserts `oneuptime-logo.svg` is
-byte-identical to the copies under `Common/UI` and `Home/Static`, so a rebrand
+`packages/Common/Tests/Server/Utils/VendorAssets.test.ts` asserts `oneuptime-logo.svg` is
+byte-identical to the copies under `packages/Common/UI` and `packages/Home/Static`, so a rebrand
 that updates one of them and not this one fails the build rather than leaving
 the acknowledge page on the old mark.
 

package/Server/Static/Vendor/README.md

@@ -7,11 +7,11 @@ CDN `<script>` does not degrade, it hangs. See
 https://github.com/OneUptime/oneuptime/issues/2570.
 
 Every service mounts this directory read-only at `/oneuptime-assets` (see
-`Common/Server/Utils/VendorAssets.ts`). Reference the files from a view by that
+`packages/Common/Server/Utils/VendorAssets.ts`). Reference the files from a view by that
 absolute path, never by a CDN URL -
-`Common/Tests/Server/Utils/OfflineAssetHygiene.test.ts` fails the build on a CDN
-URL in any `.ejs` under `Common/Server/Views`, `App/FeatureSet/*/{Views,views}`
-or `Home/Views`.
+`packages/Common/Tests/Server/Utils/OfflineAssetHygiene.test.ts` fails the build on a CDN
+URL in any `.ejs` under `packages/Common/Server/Views`, `packages/App/FeatureSet/*/{Views,views}`
+or `packages/Home/Views`.
 
 ## Contents
 
@@ -19,10 +19,10 @@ or `Home/Views`.
 | -------------------------- | ----------------------------------------------------------- |
 | `tailwind/tailwind-3.4.5.js` | Tailwind Play CDN build 3.4.5                              |
 | `highlight/`               | highlight.js 11.11.1, from cdnjs                             |
-| `fonts/InterVariable.woff2` | Inter variable font, byte-identical to the copies under `App/FeatureSet/{Docs,APIReference}/Static/fonts/` |
+| `fonts/InterVariable.woff2` | Inter variable font, byte-identical to the copies under `packages/App/FeatureSet/{Docs,APIReference}/Static/fonts/` |
 
 The Tailwind file is the **only** copy in the tree. The five frontends used to
-commit one each; `Common/UI/esbuild-config.js` now copies this one into each
+commit one each; `packages/Common/UI/esbuild-config.js` now copies this one into each
 `public/assets/js/` at build time, next to where it already copies Monaco, and
 the built copies are gitignored. Their `index.ejs` still loads it from their own
 prefix (`/dashboard/assets/js/...`) rather than through `/oneuptime-assets` - the
@@ -49,7 +49,7 @@ highlighting offline.
 
 ```bash
 BASE="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.1"
-DEST="Common/Server/Static/Vendor/highlight"
+DEST="packages/Common/Server/Static/Vendor/highlight"
 
 curl -sSfL "$BASE/highlight.min.js" -o "$DEST/highlight.min.js"
 

package/Server/Types/Database/Permissions/OwnedScopePermission.ts

@@ -62,13 +62,19 @@ export default class OwnedScopePermission {
 
     /*
      * Owned scope only restricts resources that can carry ownership:
-     * operational resources (own *OwnerUser / *OwnerTeam tables) or
+     * operational resources, explicitly registered ownership roots, or
      * nested resources that inherit ownership via @OwnedThrough. For
      * everything else (settings / config tables like IncidentState,
      * Label, Team, etc.) the table-level permission check is the only
      * gate — Owned has no resources to scope to, so it's a no-op.
+     * Registry membership only enables ownership filtering; operational
+     * wildcard grants still require the existing decorator.
      */
-    if (!model.isOperationalResource && !model.ownedThrough) {
+    if (
+      !model.isOperationalResource &&
+      !model.ownedThrough &&
+      !this.getOwnerTableRegistry().has(model.constructor.name)
+    ) {
       return query;
     }
 
@@ -212,6 +218,15 @@ export default class OwnedScopePermission {
     }
   }
 
+  private static getOwnerTableRegistry(): Map<string, OwnerTablePair> {
+    /*
+     * Services in this registry extend DatabaseService, which imports this
+     * permission class. Resolve at request time after both classes exist.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+    return require("./OwnerTableRegistry").default;
+  }
+
   /*
    * Computes the set of resource IDs the requesting user can access via
    * ownership: those where they personally sit in *OwnerUser OR where any of
@@ -244,14 +259,8 @@ export default class OwnedScopePermission {
       : // eslint-disable-next-line @typescript-eslint/no-explicit-any
         [(modelType as any).name];
 
-    /*
-     * Lazy require to avoid the circular dep cycle: this file is reachable
-     * from DatabaseService at module-load time, and the registry imports
-     * services that extend DatabaseService.
-     */
     const ownerTableRegistry: Map<string, OwnerTablePair> =
-      // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
-      require("./OwnerTableRegistry").default;
+      this.getOwnerTableRegistry();
 
     const seen: Set<string> = new Set<string>();
 

package/Server/Types/Database/Permissions/OwnerTableRegistry.ts

@@ -30,6 +30,18 @@ import CloudResourceOwnerTeamService from "../../../Services/CloudResourceOwnerT
 import CloudResourceOwnerUserService from "../../../Services/CloudResourceOwnerUserService";
 import RumApplicationOwnerTeamService from "../../../Services/RumApplicationOwnerTeamService";
 import RumApplicationOwnerUserService from "../../../Services/RumApplicationOwnerUserService";
+import ProxmoxClusterOwnerTeamService from "../../../Services/ProxmoxClusterOwnerTeamService";
+import ProxmoxClusterOwnerUserService from "../../../Services/ProxmoxClusterOwnerUserService";
+import CephClusterOwnerTeamService from "../../../Services/CephClusterOwnerTeamService";
+import CephClusterOwnerUserService from "../../../Services/CephClusterOwnerUserService";
+import DockerSwarmClusterOwnerTeamService from "../../../Services/DockerSwarmClusterOwnerTeamService";
+import DockerSwarmClusterOwnerUserService from "../../../Services/DockerSwarmClusterOwnerUserService";
+import VMwareVCenterOwnerTeamService from "../../../Services/VMwareVCenterOwnerTeamService";
+import VMwareVCenterOwnerUserService from "../../../Services/VMwareVCenterOwnerUserService";
+import IoTFleetOwnerTeamService from "../../../Services/IoTFleetOwnerTeamService";
+import IoTFleetOwnerUserService from "../../../Services/IoTFleetOwnerUserService";
+import NetworkDeviceOwnerTeamService from "../../../Services/NetworkDeviceOwnerTeamService";
+import NetworkDeviceOwnerUserService from "../../../Services/NetworkDeviceOwnerUserService";
 import StatusPageOwnerTeamService from "../../../Services/StatusPageOwnerTeamService";
 import StatusPageOwnerUserService from "../../../Services/StatusPageOwnerUserService";
 import WorkflowOwnerTeamService from "../../../Services/WorkflowOwnerTeamService";
@@ -49,6 +61,12 @@ import KubernetesClusterService from "../../../Services/KubernetesClusterService
 import ServerlessFunctionService from "../../../Services/ServerlessFunctionService";
 import CloudResourceService from "../../../Services/CloudResourceService";
 import RumApplicationService from "../../../Services/RumApplicationService";
+import ProxmoxClusterService from "../../../Services/ProxmoxClusterService";
+import CephClusterService from "../../../Services/CephClusterService";
+import DockerSwarmClusterService from "../../../Services/DockerSwarmClusterService";
+import VMwareVCenterService from "../../../Services/VMwareVCenterService";
+import IoTFleetService from "../../../Services/IoTFleetService";
+import NetworkDeviceService from "../../../Services/NetworkDeviceService";
 
 /*
  * Maps an operational model name (e.g. "Monitor") to the two services that
@@ -248,6 +266,70 @@ const ownerTableRegistry: Map<string, OwnerTablePair> = new Map<
       modelService: RumApplicationService,
     },
   ],
+  [
+    "ProxmoxCluster",
+    {
+      ownerUserService: ProxmoxClusterOwnerUserService,
+      ownerTeamService: ProxmoxClusterOwnerTeamService,
+      fkColumn: "proxmoxClusterId",
+      canOwnTelemetry: true,
+      modelService: ProxmoxClusterService,
+    },
+  ],
+  [
+    "CephCluster",
+    {
+      ownerUserService: CephClusterOwnerUserService,
+      ownerTeamService: CephClusterOwnerTeamService,
+      fkColumn: "cephClusterId",
+      canOwnTelemetry: true,
+      modelService: CephClusterService,
+    },
+  ],
+  [
+    "DockerSwarmCluster",
+    {
+      ownerUserService: DockerSwarmClusterOwnerUserService,
+      ownerTeamService: DockerSwarmClusterOwnerTeamService,
+      fkColumn: "dockerSwarmClusterId",
+      canOwnTelemetry: true,
+      modelService: DockerSwarmClusterService,
+    },
+  ],
+  [
+    "VMwareVCenter",
+    {
+      ownerUserService: VMwareVCenterOwnerUserService,
+      ownerTeamService: VMwareVCenterOwnerTeamService,
+      fkColumn: "vmwareVCenterId",
+      canOwnTelemetry: true,
+      modelService: VMwareVCenterService,
+    },
+  ],
+  [
+    /*
+     * IoT telemetry carries the fleet ID in primaryEntityId even though its
+     * primaryEntityType discriminator is IoTDevice. Ownership is fleet-wide.
+     */
+    "IoTFleet",
+    {
+      ownerUserService: IoTFleetOwnerUserService,
+      ownerTeamService: IoTFleetOwnerTeamService,
+      fkColumn: "iotFleetId",
+      canOwnTelemetry: true,
+      modelService: IoTFleetService,
+    },
+  ],
+  [
+    "NetworkDevice",
+    {
+      ownerUserService: NetworkDeviceOwnerUserService,
+      ownerTeamService: NetworkDeviceOwnerTeamService,
+      fkColumn: "networkDeviceId",
+      canOwnTelemetry: true,
+      modelService: NetworkDeviceService,
+    },
+  ],
   [
     "Workflow",
     {

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/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.