@oneuptime/common 14.0.9 → 14.0.10

package/Types/AutoRemediation/AiRemediationCommandPlan.ts

@@ -8,6 +8,15 @@ import {
   AiRemediationCommandPolicyVerdict,
   MAX_COMMAND_LENGTH_CHARS,
 } from "./AiRemediationCommandPolicyVerdict";
+import AiResourceType, {
+  AI_RESOURCE_TYPE_INFO,
+  isAiResourceType,
+} from "../ResourceAiAgent/AiResourceType";
+import {
+  RESOURCE_AI_ALLOW_WRITES_ENV,
+  RESOURCE_AI_WRITE_TARGETS_ENV,
+  ResourceCommandTier,
+} from "../ResourceAiAgent/ResourceAiAccess";
 
 /*
  * Defined in a leaf module of their own (no imports) so the pure kubectl
@@ -32,12 +41,17 @@ export { AiRemediationCommandPolicyVerdict, MAX_COMMAND_LENGTH_CHARS };
  * The only step types an AI remediation run may compose. The structured
  * Kubernetes step (restart/scale) stays runbook-only; AI reaches a cluster
  * through the Kubectl step instead, whose argv is tiered by KubectlPolicy
- * and which targets a Runner the cluster's AI page bound.
+ * and which targets a Runner the cluster's AI page bound. Every other
+ * infrastructure resource (Docker, Podman, Swarm, Proxmox, VMware, Ceph, a
+ * database server, a host) is reached through ResourceCommand, whose argv
+ * is tiered by the resource command policy and which targets the
+ * resource's own AI agent — never a Runner.
  */
 export const AI_COMMAND_STEP_TYPES: Array<RunbookStepType> = [
   RunbookStepType.Bash,
   RunbookStepType.SSH,
   RunbookStepType.Kubectl,
+  RunbookStepType.ResourceCommand,
 ];
 
 export enum AiRemediationCommandExecutionStatus {
@@ -84,6 +98,14 @@ export interface AiRemediationCommand {
   sequence: number;
   // One of AI_COMMAND_STEP_TYPES. SSH requires credentialId.
   stepType: RunbookStepType;
+  /*
+   * The access target the command runs through. For Bash/SSH (and a
+   * Kubectl step through a Runner) a Runner row; for a Kubectl step through
+   * the Kubernetes AI agent the KubernetesAiAgent row id and
+   * KUBERNETES_AI_AGENT_DISPLAY_NAME; for a ResourceCommand step the
+   * ResourceAiAgent row id and the type's agentDisplayName ("Docker AI
+   * agent").
+   */
   runnerId: string;
   runnerNameSnapshot: string;
   credentialId?: string | undefined;
@@ -96,6 +118,17 @@ export interface AiRemediationCommand {
   kubernetesClusterId?: string | undefined;
   kubernetesClusterNameSnapshot?: string | undefined;
   kubectlTier?: KubectlCommandTier | undefined;
+  /*
+   * ResourceCommand only: the resource the command runs against and the
+   * tier the resource command policy assigned when the plan was composed.
+   * The tier is informational on the card; execution re-evaluates it. A
+   * ResourceCommand step never carries a credential — the resource's AI
+   * agent uses only credentials from its own environment.
+   */
+  resourceType?: AiResourceType | undefined;
+  resourceId?: string | undefined;
+  resourceNameSnapshot?: string | undefined;
+  resourceCommandTier?: ResourceCommandTier | undefined;
   command: string;
   timeoutInMs: number;
   // Why the AI wants to run this — shown verbatim on the approval card.
@@ -286,6 +319,62 @@ export const KUBECTL_BYPASS_MODE_SUMMARY: string =
 
 export const KUBECTL_EVERY_MODE_LIMITS_SUMMARY: string = `In every mode, Bypass approval included: ${KUBECTL_NEVER_RUNS_SUMMARY}; ${KUBECTL_ALWAYS_ASKS_SUMMARY}; the cluster's in-cluster Runner never changes its own namespace, nor a namespace outside the ones its chart lets it change, nor nodes when its chart turned node operations off; and an unattended run becomes a proposal when the hourly per-cluster circuit breaker trips or another unattended round already holds the cluster.`;
 
+/*
+ * The resource command tiers and the unattended resource modes in the words
+ * every resource remediation prompt, tool description and feed item uses —
+ * for the Docker and Podman hosts, Docker Swarm, Proxmox, VMware and Ceph
+ * clusters, database servers and hosts reached through their resource AI
+ * agents. They restate the ResourceCommandTier and ResourceAiRemediationMode
+ * doc comments in Types/ResourceAiAgent/ResourceAiAccess and must keep
+ * matching them — and the resource command policy (ResourceCommandPolicy),
+ * which is what actually decides. What each kind of resource accepts is its
+ * tool policy's own guide (ResourceCommandPolicy.getWriteCommandGuide); these
+ * are the rules every kind shares. One copy, so a prompt can never describe
+ * a tier the policy no longer has.
+ */
+
+// SafeWrite: what an Automatic resource runs without a human.
+export const RESOURCE_SAFE_CHANGES_SUMMARY: string =
+  "a reversible change to exactly ONE named object — restart or start one container, a rolling restart of one service, start one VM, restart one unit, cancel one query — never several objects at once";
+
+// RiskyWrite: needs a human unless the allowlist names it or approvals are bypassed.
+export const RESOURCE_RISKIER_CHANGES_SUMMARY: string =
+  "a change that can take something down or alter what runs — stop, kill or pause a container, update limits, scale a service to zero, shut down, power off or reset a VM, mark an OSD out, stop a unit, terminate a session — and a change to several objects at once";
+
+/*
+ * Asks a human whatever the resource's mode, allowlist included: what the
+ * resource command policy marks requiresHuman (the canonical mode text in
+ * ResourceAiAccess).
+ */
+export const RESOURCE_ALWAYS_ASKS_SUMMARY: string =
+  "a change the resource's command policy marks as always needing a human (draining a Swarm node, migrating a VM, putting an ESXi host into maintenance, killing a process on a host, ...) always needs a human, in every mode — Bypass approval and the allowlist included";
+
+// Denied: never runs, whoever approves it.
+export const RESOURCE_NEVER_RUNS_SUMMARY: string =
+  "destructive commands never run, even with approval: exec, run, rm, prune, deleting or destroying anything, anything that reads or changes credentials, anything the resource's command policy does not know, and anything written as a shell line (pipes, redirects, ;, &&, $( ), sudo)";
+
+// How the resource's allowlist is read.
+export const RESOURCE_ALLOWLIST_SUMMARY: string =
+  "the resource's command allowlist is matched word by word: a pattern must have exactly as many words as the command, a * stands for exactly one whole word (never part of one), and every other word must be spelled exactly as the command spells it";
+
+/*
+ * The every-mode clause about unattended resource runs (the resource
+ * sibling of ClusterAccessContext's UNATTENDED_ROUND_BECOMES_PROPOSAL_SUMMARY).
+ */
+export const RESOURCE_UNATTENDED_ROUND_BECOMES_PROPOSAL_SUMMARY: string =
+  "an unattended run becomes a proposal when the hourly per-resource circuit breaker trips or another unattended round already holds the resource";
+
+export const RESOURCE_AUTOMATIC_MODE_SUMMARY: string = `Automatic: safe changes run without a human (${RESOURCE_SAFE_CHANGES_SUMMARY}). A riskier change (${RESOURCE_RISKIER_CHANGES_SUMMARY}) never runs without one: when the round could only find riskier fixes it ends by proposing exactly those for one-click approval; when it also ran safe fixes, a riskier fix is proposed only if verification shows the safe ones did not recover the signal (the follow-up round, which asks). Shapes on the resource's command allowlist run on their own.`;
+
+/*
+ * Interpolated into prompts and feed copy on its own, so it names the
+ * exceptions instead of pointing at a list "below".
+ */
+export const RESOURCE_BYPASS_MODE_SUMMARY: string =
+  "Bypass approval: AI does not ask. Every change the policy allows — safe AND riskier — runs on its own, follow-up rounds included, except for what always needs a human.";
+
+export const RESOURCE_EVERY_MODE_LIMITS_SUMMARY: string = `In every mode, Bypass approval included: ${RESOURCE_NEVER_RUNS_SUMMARY}; ${RESOURCE_ALWAYS_ASKS_SUMMARY}; the resource's AI agent changes nothing unless it was started with ${RESOURCE_AI_ALLOW_WRITES_ENV}=true, never changes its own protected targets (itself and what it runs in), and with ${RESOURCE_AI_WRITE_TARGETS_ENV} set changes only the targets it names; and ${RESOURCE_UNATTENDED_ROUND_BECOMES_PROPOSAL_SUMMARY}.`;
+
 export class AiRemediationCommandPlanUtil {
   /*
    * Parse a jsonb column value back into a typed plan. Fail-closed: any
@@ -348,6 +437,28 @@ export class AiRemediationCommandPlanUtil {
         return null;
       }
 
+      /*
+       * A ResourceCommand step names its resource by type and id, runs
+       * through the resource's AI agent (runnerId holds the ResourceAiAgent
+       * id) and never carries a credential or a cluster. Anything else is a
+       * plan this build cannot execute safely, so the whole plan is refused.
+       */
+      let resourceFields: Pick<
+        AiRemediationCommand,
+        | "resourceType"
+        | "resourceId"
+        | "resourceNameSnapshot"
+        | "resourceCommandTier"
+      > | null = null;
+
+      if (stepType === RunbookStepType.ResourceCommand) {
+        resourceFields = AiRemediationCommandPlanUtil.parseResourceFields(obj);
+
+        if (!resourceFields) {
+          return null;
+        }
+      }
+
       const kubectlTierRaw: string = String(obj["kubectlTier"] || "");
       const kubectlTier: KubectlCommandTier | undefined = Object.values(
         KubectlCommandTier,
@@ -383,7 +494,10 @@ export class AiRemediationCommandPlanUtil {
         runnerNameSnapshot:
           typeof obj["runnerNameSnapshot"] === "string"
             ? obj["runnerNameSnapshot"]
-            : "Runner",
+            : resourceFields?.resourceType
+              ? AI_RESOURCE_TYPE_INFO[resourceFields.resourceType]
+                  .agentDisplayName
+              : "Runner",
         credentialId:
           typeof obj["credentialId"] === "string"
             ? obj["credentialId"]
@@ -401,6 +515,7 @@ export class AiRemediationCommandPlanUtil {
             ? obj["kubernetesClusterNameSnapshot"]
             : undefined,
         kubectlTier,
+        ...(resourceFields || {}),
         command: command,
         timeoutInMs: timeoutInMs,
         rationale: typeof obj["rationale"] === "string" ? obj["rationale"] : "",
@@ -461,6 +576,72 @@ export class AiRemediationCommandPlanUtil {
     return plan;
   }
 
+  /*
+   * The resource fields of a stored ResourceCommand step, or null when the
+   * step must not be trusted: an unknown resourceType, a blank resourceId,
+   * any credential or cluster field, or a tier that is Denied or not a
+   * tier at all.
+   */
+  private static parseResourceFields(
+    obj: JSONObject,
+  ): Pick<
+    AiRemediationCommand,
+    | "resourceType"
+    | "resourceId"
+    | "resourceNameSnapshot"
+    | "resourceCommandTier"
+  > | null {
+    const resourceType: unknown = obj["resourceType"];
+
+    if (!isAiResourceType(resourceType)) {
+      return null;
+    }
+
+    const resourceId: unknown = obj["resourceId"];
+
+    if (typeof resourceId !== "string" || !resourceId.trim()) {
+      return null;
+    }
+
+    for (const field of [
+      "credentialId",
+      "credentialNameSnapshot",
+      "credential",
+      "kubernetesClusterId",
+    ]) {
+      if (obj[field] !== undefined && obj[field] !== null) {
+        return null;
+      }
+    }
+
+    const tierRaw: unknown = obj["resourceCommandTier"];
+    let resourceCommandTier: ResourceCommandTier | undefined = undefined;
+
+    if (tierRaw !== undefined && tierRaw !== null && tierRaw !== "") {
+      if (
+        typeof tierRaw !== "string" ||
+        !(Object.values(ResourceCommandTier) as Array<string>).includes(
+          tierRaw,
+        ) ||
+        tierRaw === ResourceCommandTier.Denied
+      ) {
+        return null;
+      }
+
+      resourceCommandTier = tierRaw as ResourceCommandTier;
+    }
+
+    return {
+      resourceType,
+      resourceId,
+      resourceNameSnapshot:
+        typeof obj["resourceNameSnapshot"] === "string"
+          ? obj["resourceNameSnapshot"]
+          : undefined,
+      resourceCommandTier,
+    };
+  }
+
   public static toJSON(plan: AiRemediationCommandPlan): JSONObject {
     return JSON.parse(JSON.stringify(plan)) as JSONObject;
   }

package/Types/Monitor/Recommendation/MonitorRecommendationCatalog.ts

@@ -51,6 +51,7 @@ import {
 import {
   RumAlertTemplate,
   getAllRumAlertTemplates,
+  getRumAlertTemplates,
 } from "../RumAlertTemplates";
 import {
   ServiceAlertTemplate,
@@ -96,8 +97,8 @@ export interface MonitorRecommendationResourceTypeDefinition {
    * Most resource types ignore the argument entirely — every Kubernetes
    * cluster is offered the same eighteen recommendations, and a
    * zero-argument function satisfies this type, so those are declared
-   * exactly as they were. Services and databases are the exceptions: see
-   * `MonitorRecommendationContext`.
+   * exactly as they were. Services, databases and RUM applications are the
+   * exceptions: see `MonitorRecommendationContext`.
    *
    * Passing no context means "nothing is known about this resource", and the
    * only honest answer to that is the context-free subset. It does NOT mean
@@ -356,28 +357,58 @@ function getIoTRecommendations(): Array<MonitorRecommendation> {
   });
 }
 
-function getRumRecommendations(): Array<MonitorRecommendation> {
+/*
+ * The RUM adapter — two functions for the same reason as Service's.
+ *
+ * `getRumRecommendations` answers "what should THIS application be offered":
+ * everything except the session replay budget alerts, which wait until the
+ * application records replays (and, for the monthly pair, has a monthly
+ * budget), because only then does the sweep write the series they watch.
+ * `getAllRumRecommendations` answers "what can an application ever be
+ * offered" — without it, a dismissed or created budget alert could not be
+ * resolved back from its id.
+ */
+function normalizeRumTemplate(
+  template: RumAlertTemplate,
+): MonitorRecommendation {
+  return normalize({
+    resourceType: MonitorRecommendationResourceType.RumApplication,
+    monitorType: template.monitorType,
+    template: template,
+    getMonitorStep: (args: MonitorRecommendationArgs) => {
+      return template.getMonitorStep({
+        rumApplicationId: args.resourceIdentifier,
+        onlineMonitorStatusId: args.onlineMonitorStatusId,
+        offlineMonitorStatusId: args.offlineMonitorStatusId,
+        defaultIncidentSeverityId: args.defaultIncidentSeverityId,
+        defaultAlertSeverityId: args.defaultAlertSeverityId,
+        monitorName: args.monitorName,
+      });
+    },
+  });
+}
+
+function getRumRecommendations(
+  context?: MonitorRecommendationContext | undefined,
+): Array<MonitorRecommendation> {
+  return getRumAlertTemplates({
+    sessionReplayEnabled: context?.sessionReplayEnabled,
+    sessionReplayHasRecorded: context?.sessionReplayHasRecorded,
+    sessionReplayMonthlyBudgetInGB: context?.sessionReplayMonthlyBudgetInGB,
+  }).map((template: RumAlertTemplate) => {
+    return normalizeRumTemplate(template);
+  });
+}
+
+function getAllRumRecommendations(): Array<MonitorRecommendation> {
   return getAllRumAlertTemplates().map((template: RumAlertTemplate) => {
-    return normalize({
-      resourceType: MonitorRecommendationResourceType.RumApplication,
-      monitorType: template.monitorType,
-      template: template,
-      getMonitorStep: (args: MonitorRecommendationArgs) => {
-        return template.getMonitorStep({
-          rumApplicationId: args.resourceIdentifier,
-          onlineMonitorStatusId: args.onlineMonitorStatusId,
-          offlineMonitorStatusId: args.offlineMonitorStatusId,
-          defaultIncidentSeverityId: args.defaultIncidentSeverityId,
-          defaultAlertSeverityId: args.defaultAlertSeverityId,
-          monitorName: args.monitorName,
-        });
-      },
-    });
+    return normalizeRumTemplate(template);
   });
 }
 
 /*
- * The Service adapter, and the only one that is two functions rather than one.
+ * The Service adapter, the first that is two functions rather than one (the
+ * RUM adapter above and the database adapter below follow its pattern).
  *
  * `getServiceRecommendations` answers "what should THIS service be offered",
  * which depends on its runtime. `getAllServiceRecommendations` answers "what
@@ -573,6 +604,7 @@ const RESOURCE_TYPE_DEFINITIONS: Array<MonitorRecommendationResourceTypeDefiniti
       identifierFieldName: "rumApplicationId",
       icon: IconProp.Globe,
       getRecommendations: getRumRecommendations,
+      getAllPossibleRecommendations: getAllRumRecommendations,
     },
     {
       resourceType: MonitorRecommendationResourceType.Service,
@@ -657,9 +689,10 @@ export default class MonitorRecommendationCatalog {
    *
    * This, not `getRecommendations(resourceType)`, is what a per-type
    * invariant has to run over: with no context a database is offered nothing
-   * at all (there is no engine-agnostic database template) and a service only
-   * its language-agnostic subset, so a check written against the context-free
-   * set would silently skip every engine- and runtime-specific template.
+   * at all (there is no engine-agnostic database template), a service only
+   * its language-agnostic subset and a RUM application none of its session
+   * replay budget alerts, so a check written against the context-free set
+   * would silently skip every engine-, runtime- and replay-specific template.
    */
   public static getAllPossibleRecommendations(
     resourceType: MonitorRecommendationResourceType,

package/Types/Monitor/Recommendation/MonitorRecommendationTypes.ts

@@ -30,6 +30,11 @@ export enum MonitorRecommendationResourceType {
   VMware = "VMware",
   Ceph = "Ceph",
   IoTDevice = "IoTDevice",
+  /*
+   * A RUM (browser) application. Its recommendation set gains the session
+   * replay storage budget alerts once it records replays — see
+   * `MonitorRecommendationContext`.
+   */
   RumApplication = "RumApplication",
   /*
    * An APM telemetry service — a backend process reporting OTel traces,
@@ -58,12 +63,14 @@ export enum MonitorRecommendationResourceType {
  * exist on a Go service, and recommending them there produces monitors that
  * silently never fire, which is worse than recommending nothing. Databases
  * are the same by engine: PostgreSQL's receiver and Redis's share no metric
- * name.
+ * name. And a RUM application is only offered its session replay budget
+ * alerts once it records replays, because only then are those metrics
+ * written for it.
  *
  * Optional everywhere, and every field inside it is optional too, so a caller
  * that knows nothing still gets the subset that is true of every resource of
- * the type — the language-agnostic recommendations for a service, and none
- * for a database — rather than a guess.
+ * the type — the language-agnostic recommendations for a service, none for a
+ * database, and no budget alerts for a RUM application — rather than a guess.
  */
 export interface MonitorRecommendationContext {
   /*
@@ -92,6 +99,31 @@ export interface MonitorRecommendationContext {
    * `null` / `undefined` mean "not known" and withhold nothing.
    */
   databaseEngineMetricsReported?: boolean | null | undefined;
+  /*
+   * A RUM application's `isSessionReplayEnabled`: the first of the three
+   * facts that decide whether it is offered its session replay storage budget
+   * alerts (see `getRumAlertTemplates`). The budget sweep only writes those
+   * metrics for an application that has session replay on AND has recorded,
+   * and the monthly ones only while it has a monthly budget; a monitor over a
+   * series nobody writes never fires.
+   *
+   * Unlike `databaseEngineMetricsReported`, `null` / `undefined` in all three
+   * mean "not known" and WITHHOLD: these alerts are an addition to a set that
+   * is complete without them, so a page that knows nothing shows exactly what
+   * it showed before they existed.
+   */
+  sessionReplayEnabled?: boolean | null | undefined;
+  /*
+   * Whether a replay was ever accepted for the application (its
+   * `sessionReplayLastChunkReceivedAt` is set). The switch alone says
+   * nothing: it is on by default, on every RUM application.
+   */
+  sessionReplayHasRecorded?: boolean | null | undefined;
+  /*
+   * Its `sessionReplayMonthlyBudgetInGB` (GiB, like every replay "GB"). Only
+   * a finite number above 0 is a budget; 0, blank and anything else is none.
+   */
+  sessionReplayMonthlyBudgetInGB?: number | null | undefined;
 }
 
 /*