@oneuptime/common 11.7.4 → 12.0.0

package/Types/AutoRemediation/AiRemediationCommandPlan.ts

@@ -0,0 +1,304 @@
+import RunbookStepType from "../Runbook/RunbookStepType";
+import { JSONObject } from "../JSON";
+
+/*
+ * The AI-composed command plan stored on
+ * AutoRemediationSuggestion.commandPlan (jsonb). Everything in here is
+ * DATA authored by an AI run and frozen at settle time — approval executes
+ * exactly what was recorded, never a re-derived command. Secret material
+ * never appears here: commands reference credentials by id and the Runner
+ * resolves them at claim time.
+ */
+
+/*
+ * The only step types an AI remediation run may compose. Kubernetes stays
+ * runbook-only: its structured restart/scale actions cannot express an
+ * arbitrary command, which is the whole point of this lane, and operators
+ * who want kubectl can expose it to a Bash command instead.
+ */
+export const AI_COMMAND_STEP_TYPES: Array<RunbookStepType> = [
+  RunbookStepType.Bash,
+  RunbookStepType.SSH,
+];
+
+export enum AiRemediationCommandPolicyVerdict {
+  /*
+   * Matched the rule's operator-authored allowlist and passed the
+   * structural chain guard — eligible for FullAuto inline execution.
+   */
+  AutoApproved = "AutoApproved",
+  // Not denylisted, but a human must approve before it runs.
+  RequiresApproval = "RequiresApproval",
+  /*
+   * Matched the hard denylist. Denied commands are never stored in a plan —
+   * the verdict exists so policy evaluation has a complete result type.
+   */
+  Denied = "Denied",
+}
+
+export enum AiRemediationCommandExecutionStatus {
+  Pending = "Pending",
+  Running = "Running",
+  Succeeded = "Succeeded",
+  Failed = "Failed",
+  // An earlier command in the plan failed, so this one never ran.
+  Skipped = "Skipped",
+}
+
+export enum AiRemediationPlanExecutionStatus {
+  NotStarted = "NotStarted",
+  Running = "Running",
+  Completed = "Completed",
+  Failed = "Failed",
+}
+
+export enum AiRemediationRollbackStatus {
+  NotAttempted = "NotAttempted",
+  Completed = "Completed",
+  Failed = "Failed",
+  // No executed command carried a rollback command.
+  NotApplicable = "NotApplicable",
+}
+
+export interface AiRemediationCommandExecutionState {
+  status: AiRemediationCommandExecutionStatus;
+  runnerJobId?: string | undefined;
+  output?: string | undefined;
+  exitCode?: number | undefined;
+  errorMessage?: string | undefined;
+  startedAt?: string | undefined; // ISO 8601
+  completedAt?: string | undefined; // ISO 8601
+}
+
+export interface AiRemediationCommand {
+  // 1-based position; plans execute strictly in sequence order.
+  sequence: number;
+  // One of AI_COMMAND_STEP_TYPES. SSH requires credentialId.
+  stepType: RunbookStepType;
+  runnerId: string;
+  runnerNameSnapshot: string;
+  credentialId?: string | undefined;
+  credentialNameSnapshot?: string | undefined;
+  command: string;
+  timeoutInMs: number;
+  // Why the AI wants to run this — shown verbatim on the approval card.
+  rationale: string;
+  expectedEffect: string;
+  /*
+   * Optional undo command, validated by the same policy as the forward
+   * command. Executed on verification failure only when it, too, passed
+   * policy (approval of the plan covers the rollback commands shown on it).
+   */
+  rollbackCommand?: string | undefined;
+  policyVerdict: AiRemediationCommandPolicyVerdict;
+  // True when a FullAuto run already executed this inline during planning.
+  wasAutoExecuted?: boolean | undefined;
+  execution?: AiRemediationCommandExecutionState | undefined;
+  rollbackExecution?: AiRemediationCommandExecutionState | undefined;
+}
+
+export interface AiRemediationCommandPlan {
+  commands: Array<AiRemediationCommand>;
+  /*
+   * Lifecycle of the approved-plan execution sweep. FullAuto inline
+   * commands are executed during the AI run itself and settle with
+   * Completed here.
+   */
+  executionStatus?: AiRemediationPlanExecutionStatus | undefined;
+  executionStartedAt?: string | undefined;
+  executionCompletedAt?: string | undefined;
+  rollbackStatus?: AiRemediationRollbackStatus | undefined;
+}
+
+// Hard caps — enforced at plan acceptance, not just in the prompt.
+export const MAX_PLAN_COMMANDS: number = 5;
+export const MAX_COMMAND_LENGTH_CHARS: number = 2000;
+export const MIN_COMMAND_TIMEOUT_MS: number = 1000;
+export const MAX_COMMAND_TIMEOUT_MS: number = 5 * 60 * 1000;
+export const DEFAULT_COMMAND_TIMEOUT_MS: number = 60 * 1000;
+
+export class AiRemediationCommandPlanUtil {
+  /*
+   * Parse a jsonb column value back into a typed plan. Fail-closed: any
+   * structural problem returns null rather than a partially-valid plan,
+   * because the executor and verifier act on what this returns.
+   */
+  public static parse(
+    json: JSONObject | undefined | null,
+  ): AiRemediationCommandPlan | null {
+    if (!json || typeof json !== "object") {
+      return null;
+    }
+
+    const commandsRaw: unknown = json["commands"];
+    if (!Array.isArray(commandsRaw) || commandsRaw.length === 0) {
+      return null;
+    }
+
+    if (commandsRaw.length > MAX_PLAN_COMMANDS) {
+      return null;
+    }
+
+    const commands: Array<AiRemediationCommand> = [];
+
+    for (const item of commandsRaw) {
+      if (!item || typeof item !== "object") {
+        return null;
+      }
+      const obj: JSONObject = item as JSONObject;
+
+      const stepType: string = String(obj["stepType"] || "");
+      if (!AI_COMMAND_STEP_TYPES.includes(stepType as RunbookStepType)) {
+        return null;
+      }
+
+      const command: string =
+        typeof obj["command"] === "string" ? obj["command"] : "";
+      const runnerId: string =
+        typeof obj["runnerId"] === "string" ? obj["runnerId"] : "";
+      if (!command.trim() || !runnerId.trim()) {
+        return null;
+      }
+
+      if (command.length > MAX_COMMAND_LENGTH_CHARS) {
+        return null;
+      }
+
+      if (
+        stepType === RunbookStepType.SSH &&
+        (typeof obj["credentialId"] !== "string" || !obj["credentialId"].trim())
+      ) {
+        return null;
+      }
+
+      const verdict: string = String(obj["policyVerdict"] || "");
+      if (
+        verdict !== AiRemediationCommandPolicyVerdict.AutoApproved &&
+        verdict !== AiRemediationCommandPolicyVerdict.RequiresApproval
+      ) {
+        // Denied commands must never have been stored.
+        return null;
+      }
+
+      const timeoutRaw: unknown = obj["timeoutInMs"];
+      const timeoutInMs: number =
+        typeof timeoutRaw === "number" && Number.isFinite(timeoutRaw)
+          ? Math.min(
+              MAX_COMMAND_TIMEOUT_MS,
+              Math.max(MIN_COMMAND_TIMEOUT_MS, Math.floor(timeoutRaw)),
+            )
+          : DEFAULT_COMMAND_TIMEOUT_MS;
+
+      commands.push({
+        sequence:
+          typeof obj["sequence"] === "number"
+            ? obj["sequence"]
+            : commands.length + 1,
+        stepType: stepType as RunbookStepType,
+        runnerId: runnerId,
+        runnerNameSnapshot:
+          typeof obj["runnerNameSnapshot"] === "string"
+            ? obj["runnerNameSnapshot"]
+            : "Runner",
+        credentialId:
+          typeof obj["credentialId"] === "string"
+            ? obj["credentialId"]
+            : undefined,
+        credentialNameSnapshot:
+          typeof obj["credentialNameSnapshot"] === "string"
+            ? obj["credentialNameSnapshot"]
+            : undefined,
+        command: command,
+        timeoutInMs: timeoutInMs,
+        rationale: typeof obj["rationale"] === "string" ? obj["rationale"] : "",
+        expectedEffect:
+          typeof obj["expectedEffect"] === "string"
+            ? obj["expectedEffect"]
+            : "",
+        rollbackCommand:
+          typeof obj["rollbackCommand"] === "string" &&
+          obj["rollbackCommand"].trim()
+            ? obj["rollbackCommand"]
+            : undefined,
+        policyVerdict: verdict as AiRemediationCommandPolicyVerdict,
+        wasAutoExecuted: obj["wasAutoExecuted"] === true,
+        execution: AiRemediationCommandPlanUtil.parseExecutionState(
+          obj["execution"],
+        ),
+        rollbackExecution: AiRemediationCommandPlanUtil.parseExecutionState(
+          obj["rollbackExecution"],
+        ),
+      });
+    }
+
+    // Execution order must be unambiguous.
+    commands.sort((a: AiRemediationCommand, b: AiRemediationCommand) => {
+      return a.sequence - b.sequence;
+    });
+
+    const plan: AiRemediationCommandPlan = { commands };
+
+    const executionStatus: string = String(json["executionStatus"] || "");
+    if (
+      Object.values(AiRemediationPlanExecutionStatus).includes(
+        executionStatus as AiRemediationPlanExecutionStatus,
+      )
+    ) {
+      plan.executionStatus =
+        executionStatus as AiRemediationPlanExecutionStatus;
+    }
+    if (typeof json["executionStartedAt"] === "string") {
+      plan.executionStartedAt = json["executionStartedAt"];
+    }
+    if (typeof json["executionCompletedAt"] === "string") {
+      plan.executionCompletedAt = json["executionCompletedAt"];
+    }
+    const rollbackStatus: string = String(json["rollbackStatus"] || "");
+    if (
+      Object.values(AiRemediationRollbackStatus).includes(
+        rollbackStatus as AiRemediationRollbackStatus,
+      )
+    ) {
+      plan.rollbackStatus = rollbackStatus as AiRemediationRollbackStatus;
+    }
+
+    return plan;
+  }
+
+  public static toJSON(plan: AiRemediationCommandPlan): JSONObject {
+    return JSON.parse(JSON.stringify(plan)) as JSONObject;
+  }
+
+  private static parseExecutionState(
+    value: unknown,
+  ): AiRemediationCommandExecutionState | undefined {
+    if (!value || typeof value !== "object") {
+      return undefined;
+    }
+    const obj: JSONObject = value as JSONObject;
+    const status: string = String(obj["status"] || "");
+    if (
+      !Object.values(AiRemediationCommandExecutionStatus).includes(
+        status as AiRemediationCommandExecutionStatus,
+      )
+    ) {
+      return undefined;
+    }
+    return {
+      status: status as AiRemediationCommandExecutionStatus,
+      runnerJobId:
+        typeof obj["runnerJobId"] === "string" ? obj["runnerJobId"] : undefined,
+      output: typeof obj["output"] === "string" ? obj["output"] : undefined,
+      exitCode:
+        typeof obj["exitCode"] === "number" ? obj["exitCode"] : undefined,
+      errorMessage:
+        typeof obj["errorMessage"] === "string"
+          ? obj["errorMessage"]
+          : undefined,
+      startedAt:
+        typeof obj["startedAt"] === "string" ? obj["startedAt"] : undefined,
+      completedAt:
+        typeof obj["completedAt"] === "string" ? obj["completedAt"] : undefined,
+    };
+  }
+}

package/Types/AutoRemediation/AutoRemediationExecutionMode.ts

@@ -0,0 +1,17 @@
+/*
+ * How a matched auto-remediation rule acts.
+ *
+ * Suggest: propose the runbook on the incident/alert and wait for a human
+ * to approve with one click. This is the default and the only mode allowed
+ * when the rule lets AI pick the runbook.
+ *
+ * FullAuto: start the runbook immediately with no human in the loop. Only
+ * available for deterministic rules (explicitly attached runbooks) and
+ * subject to the per-rule hourly circuit breaker.
+ */
+enum AutoRemediationExecutionMode {
+  Suggest = "Suggest",
+  FullAuto = "FullAuto",
+}
+
+export default AutoRemediationExecutionMode;

package/Types/AutoRemediation/AutoRemediationSuggestionStatus.ts

@@ -0,0 +1,35 @@
+/*
+ * Lifecycle of an auto-remediation suggestion — the approvable action
+ * object a matched rule attaches to an incident or alert.
+ *
+ * Planning:       an AI planning run is choosing the best runbook.
+ * Suggested:      a runbook is proposed; waiting for one-click approval.
+ * Approved:       a human approved it and the runbook execution started.
+ * AutoExecuted:   a FullAuto rule started the runbook with no human in the loop.
+ * Dismissed:      a human rejected the proposal.
+ * NoneApplicable: the AI judged that no candidate runbook applies.
+ */
+enum AutoRemediationSuggestionStatus {
+  Planning = "Planning",
+  Suggested = "Suggested",
+  Approved = "Approved",
+  AutoExecuted = "AutoExecuted",
+  Dismissed = "Dismissed",
+  NoneApplicable = "NoneApplicable",
+}
+
+export default AutoRemediationSuggestionStatus;
+
+export class AutoRemediationSuggestionStatusHelper {
+  // Terminal suggestions never change again; open ones can still be actioned.
+  public static isTerminalStatus(
+    status: AutoRemediationSuggestionStatus,
+  ): boolean {
+    return (
+      status === AutoRemediationSuggestionStatus.Approved ||
+      status === AutoRemediationSuggestionStatus.AutoExecuted ||
+      status === AutoRemediationSuggestionStatus.Dismissed ||
+      status === AutoRemediationSuggestionStatus.NoneApplicable
+    );
+  }
+}

package/Types/AutoRemediation/AutoRemediationSuggestionType.ts

@@ -0,0 +1,17 @@
+/*
+ * What kind of action an auto-remediation suggestion proposes.
+ *
+ * Runbook:     the suggestion proposes starting a pre-authored runbook
+ *              (deterministic rules and aiSelectsRunbook rules).
+ * CommandPlan: the suggestion carries an AI-composed command plan — concrete
+ *              Bash/SSH commands targeted at specific Runners, stored on
+ *              the suggestion's commandPlan column. Approval executes the
+ *              plan; FullAuto rules may have already executed allowlisted
+ *              commands inline.
+ */
+enum AutoRemediationSuggestionType {
+  Runbook = "Runbook",
+  CommandPlan = "CommandPlan",
+}
+
+export default AutoRemediationSuggestionType;

package/Types/AutoRemediation/AutoRemediationTriggerEntity.ts

@@ -0,0 +1,11 @@
+/*
+ * Entity type an auto-remediation rule listens for. Unlike runbook rules,
+ * auto-remediation deliberately excludes scheduled maintenance — planned
+ * events are not something to remediate.
+ */
+enum AutoRemediationTriggerEntity {
+  Incident = "Incident",
+  Alert = "Alert",
+}
+
+export default AutoRemediationTriggerEntity;

package/Types/AutoRemediation/AutoRemediationVerificationStatus.ts

@@ -0,0 +1,21 @@
+/*
+ * Outcome verification for an executed remediation. A remediation is not
+ * done when the runbook exits — it is done when the subject's monitors are
+ * back to an operational state (or the incident/alert was resolved) within
+ * the verification window.
+ *
+ * Pending:  the runbook was started; the verifier is watching for recovery.
+ * Verified: the subject recovered (or was resolved) within the window.
+ * Failed:   the runbook failed, did not finish in time, or the service did
+ *           not recover within the window — escalation continues as normal.
+ * Skipped:  nothing to verify against (e.g. a manual incident with no
+ *           monitors).
+ */
+enum AutoRemediationVerificationStatus {
+  Pending = "Pending",
+  Verified = "Verified",
+  Failed = "Failed",
+  Skipped = "Skipped",
+}
+
+export default AutoRemediationVerificationStatus;

package/Types/CustomField/CustomFieldDropdownOption.ts

@@ -0,0 +1,190 @@
+export interface CustomFieldDropdownOption {
+  value: string;
+  color?: string | undefined;
+}
+
+const HEX_COLOR_REGEX: RegExp = /^#[0-9a-f]{6}$/i;
+
+export type NormalizeCustomFieldDropdownOptionColorFunction = (
+  value: unknown,
+) => string | undefined;
+
+export const normalizeCustomFieldDropdownOptionColor: NormalizeCustomFieldDropdownOptionColorFunction =
+  (value: unknown): string | undefined => {
+    if (typeof value !== "string") {
+      return undefined;
+    }
+
+    const color: string = value.trim().toLowerCase();
+
+    return HEX_COLOR_REGEX.test(color) ? color : undefined;
+  };
+
+const normalizeOption: (
+  value: unknown,
+) => CustomFieldDropdownOption | undefined = (
+  value: unknown,
+): CustomFieldDropdownOption | undefined => {
+  if (typeof value === "string") {
+    const optionValue: string = value.trim();
+
+    return optionValue ? { value: optionValue } : undefined;
+  }
+
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+
+  const optionValue: unknown =
+    (value as Record<string, unknown>)["value"] ??
+    (value as Record<string, unknown>)["label"];
+
+  if (typeof optionValue !== "string" || !optionValue.trim()) {
+    return undefined;
+  }
+
+  const option: CustomFieldDropdownOption = {
+    value: optionValue.trim(),
+  };
+  const color: string | undefined = normalizeCustomFieldDropdownOptionColor(
+    (value as Record<string, unknown>)["color"],
+  );
+
+  if (color) {
+    option.color = color;
+  }
+
+  return option;
+};
+
+const isStructuredOptions: (value: unknown) => value is Array<unknown> = (
+  value: unknown,
+): value is Array<unknown> => {
+  return (
+    Array.isArray(value) &&
+    value.some((option: unknown) => {
+      return Boolean(
+        option &&
+          typeof option === "object" &&
+          !Array.isArray(option) &&
+          Object.prototype.hasOwnProperty.call(option, "color"),
+      );
+    })
+  );
+};
+
+export type ParseCustomFieldDropdownOptionsFunction = (
+  value: unknown,
+) => Array<CustomFieldDropdownOption>;
+
+/*
+ * Dropdown options used to be stored as one value per line. Colored options
+ * use a compact JSON array, while this parser deliberately keeps accepting
+ * the original newline format so existing custom fields need no migration.
+ */
+export const parseCustomFieldDropdownOptions: ParseCustomFieldDropdownOptionsFunction =
+  (value: unknown): Array<CustomFieldDropdownOption> => {
+    if (typeof value !== "string" || !value.trim()) {
+      return [];
+    }
+
+    const serialized: string = value.trim();
+
+    if (serialized.startsWith("[")) {
+      try {
+        const parsed: unknown = JSON.parse(serialized);
+
+        if (isStructuredOptions(parsed)) {
+          return parsed
+            .map((option: unknown) => {
+              return normalizeOption(option);
+            })
+            .filter(
+              (
+                option: CustomFieldDropdownOption | undefined,
+              ): option is CustomFieldDropdownOption => {
+                return Boolean(option);
+              },
+            );
+        }
+      } catch {
+        /*
+         * Fall through to the legacy format. A value may legitimately start
+         * with "[", and malformed data must remain editable instead of vanish.
+         */
+      }
+    }
+
+    return serialized
+      .split("\n")
+      .map((line: string) => {
+        return normalizeOption(line);
+      })
+      .filter(
+        (
+          option: CustomFieldDropdownOption | undefined,
+        ): option is CustomFieldDropdownOption => {
+          return Boolean(option);
+        },
+      );
+  };
+
+export type SerializeCustomFieldDropdownOptionsFunction = (
+  options: Array<CustomFieldDropdownOption>,
+) => string;
+
+export const serializeCustomFieldDropdownOptions: SerializeCustomFieldDropdownOptionsFunction =
+  (options: Array<CustomFieldDropdownOption>): string => {
+    const normalizedOptions: Array<CustomFieldDropdownOption> = (options || [])
+      .map((option: CustomFieldDropdownOption) => {
+        return normalizeOption(option);
+      })
+      .filter(
+        (
+          option: CustomFieldDropdownOption | undefined,
+        ): option is CustomFieldDropdownOption => {
+          return Boolean(option);
+        },
+      );
+
+    if (normalizedOptions.length === 0) {
+      return "";
+    }
+
+    if (
+      normalizedOptions.every((option: CustomFieldDropdownOption) => {
+        return !option.color;
+      })
+    ) {
+      return normalizedOptions
+        .map((option: CustomFieldDropdownOption) => {
+          return option.value;
+        })
+        .join("\n");
+    }
+
+    return JSON.stringify(normalizedOptions);
+  };
+
+export type GetCustomFieldDropdownOptionFunction = (
+  serializedOptions: unknown,
+  value: unknown,
+) => CustomFieldDropdownOption | undefined;
+
+export const getCustomFieldDropdownOption: GetCustomFieldDropdownOptionFunction =
+  (
+    serializedOptions: unknown,
+    value: unknown,
+  ): CustomFieldDropdownOption | undefined => {
+    if (value === undefined || value === null) {
+      return undefined;
+    }
+
+    const optionValue: string = String(value);
+
+    return parseCustomFieldDropdownOptions(serializedOptions).find(
+      (option: CustomFieldDropdownOption) => {
+        return option.value === optionValue;
+      },
+    );
+  };

package/Types/Dashboard/DashboardComponentType.ts

@@ -2,6 +2,7 @@ enum DashboardComponentType {
   Chart = `Chart`,
   Value = `Value`,
   Text = `Text`,
+  Clock = `Clock`,
   Table = `Table`,
   Gauge = `Gauge`,
   LogStream = `LogStream`,
@@ -38,6 +39,7 @@ enum DashboardComponentType {
   DockerSwarmServiceList = `DockerSwarmServiceList`,
   CephOsdList = `CephOsdList`,
   CephPoolList = `CephPoolList`,
+  Html = `Html`,
 }
 
 export default DashboardComponentType;

package/Types/Dashboard/DashboardComponents/ComponentArgument.ts

@@ -18,6 +18,10 @@ export enum ComponentInputType {
   MultiSelectDropdown = "MultiSelectDropdown",
   EntityDropdown = "EntityDropdown",
   EntityMultiSelectDropdown = "EntityMultiSelectDropdown",
+  // Monaco code editors, one per language.
+  Html = "Html",
+  Css = "Css",
+  JavaScript = "JavaScript",
 }
 
 export enum EntityFilterModelType {

package/Types/Dashboard/DashboardComponents/DashboardClockComponent.ts

@@ -0,0 +1,45 @@
+import ObjectID from "../../ObjectID";
+import DashboardComponentType from "../DashboardComponentType";
+import BaseComponent from "./DashboardBaseComponent";
+
+/** How the time is drawn — digits, or a drawn clock face. */
+export enum ClockWidgetFace {
+  Digital = "Digital",
+  Analog = "Analog",
+}
+
+/**
+ * 12h vs 24h. `Auto` follows whatever the viewer's browser locale implies
+ * (OneUptimeDate.getUserPrefers12HourFormat), so a dashboard shared between a
+ * US and a European team reads naturally for both without either of them
+ * having to re-configure the widget.
+ */
+export enum ClockWidgetHourFormat {
+  Auto = "Auto",
+  TwelveHour = "12 Hour",
+  TwentyFourHour = "24 Hour",
+}
+
+export default interface DashboardClockComponent extends BaseComponent {
+  componentType: DashboardComponentType.Clock;
+  componentId: ObjectID;
+  arguments: {
+    /*
+     * IANA zone name (e.g. "America/New_York"), matching the values in the
+     * Timezone enum. Empty means "the zone the viewer is reading this in",
+     * which is what a single clock on a personal dashboard should do.
+     */
+    timezone?: string | undefined;
+    /*
+     * Caption under the time. Empty falls back to the city in the IANA name
+     * ("Asia/Kolkata" -> "Kolkata"), so an unconfigured clock is still
+     * labelled.
+     */
+    label?: string | undefined;
+    clockFace?: ClockWidgetFace | undefined;
+    hourFormat?: ClockWidgetHourFormat | undefined;
+    showSeconds?: boolean | undefined;
+    showDate?: boolean | undefined;
+    showTimezoneAbbreviation?: boolean | undefined;
+  };
+}