@oneuptime/common 14.0.9 → 14.0.10

package/Tests/Utils/SessionReplay/SessionReplayBudgetMetricType.test.ts

@@ -0,0 +1,383 @@
+import AggregationType from "../../../Types/BaseDatabase/AggregationType";
+import SessionReplayBudgetMetricType from "../../../Types/Rum/SessionReplayBudgetMetricType";
+import SessionReplayBudgetMetricTypeUtil, {
+  SESSION_REPLAY_BUDGET_METRIC_INTERVAL_MINUTES,
+  SESSION_REPLAY_BUDGET_METRIC_PROJECT_ID_ATTRIBUTE,
+  SESSION_REPLAY_BUDGET_METRIC_RUM_APPLICATION_ID_ATTRIBUTE,
+  SESSION_REPLAY_BUDGET_METRIC_RUM_APPLICATION_NAME_ATTRIBUTE,
+  SESSION_REPLAY_METRIC_NAME_PREFIX,
+} from "../../../Utils/SessionReplay/SessionReplayBudgetMetricType";
+import MetricUnitUtil from "../../../Utils/MetricUnitUtil";
+import { MutableMetricService } from "../../../Server/Services/MutableMetricService";
+import { describe, expect, test } from "@jest/globals";
+
+/*
+ * SessionReplayBudgetMetricTypeUtil is the one table every side of the
+ * session replay budget metrics reads: the sweep registers each name's unit
+ * and description from it, the alert templates read the names, billing
+ * excludes by getAll(), and OTLP ingest refuses isReservedMetricName(). Two
+ * kinds of test, as in SloMetricType.test.ts:
+ *
+ *   - Targeted: the exact name / unit / aggregation per member, because a
+ *     stored row, a monitor threshold or a chart depends on each.
+ *   - Invariant: every lookup resolves for EVERY enum member. The switches
+ *     throw on an unknown value, so a member added to the enum and forgotten
+ *     in one switch fails here instead of inside the worker.
+ */
+
+const ALL_BUDGET_METRIC_TYPES: Array<SessionReplayBudgetMetricType> =
+  Object.values(SessionReplayBudgetMetricType);
+
+// A value outside the enum, to drive the throwing default branches.
+const UNKNOWN_METRIC_TYPE: SessionReplayBudgetMetricType =
+  "oneuptime.rum.session.replay.budget.not.a.metric" as SessionReplayBudgetMetricType;
+
+describe("SessionReplayBudgetMetricType names", () => {
+  /*
+   * The names are an append-only contract: every point already stored and
+   * every monitor already watching one is keyed on the exact string.
+   */
+  test("are exactly the four published names", () => {
+    expect(SessionReplayBudgetMetricType.ProjectDailyUsedBytes).toBe(
+      "oneuptime.rum.session.replay.budget.project.daily.used.bytes",
+    );
+    expect(SessionReplayBudgetMetricType.ProjectDailyUsedPercent).toBe(
+      "oneuptime.rum.session.replay.budget.project.daily.used.percent",
+    );
+    expect(SessionReplayBudgetMetricType.ApplicationMonthlyUsedBytes).toBe(
+      "oneuptime.rum.session.replay.budget.application.monthly.used.bytes",
+    );
+    expect(SessionReplayBudgetMetricType.ApplicationMonthlyUsedPercent).toBe(
+      "oneuptime.rum.session.replay.budget.application.monthly.used.percent",
+    );
+    expect(ALL_BUDGET_METRIC_TYPES).toHaveLength(4);
+  });
+
+  test.each(ALL_BUDGET_METRIC_TYPES)(
+    "%s lives under the reserved prefix, in lower case, within the catalog's name length",
+    (metricType: SessionReplayBudgetMetricType) => {
+      expect(metricType.startsWith(SESSION_REPLAY_METRIC_NAME_PREFIX)).toBe(
+        true,
+      );
+      // OTLP ingest lowercases names; a mixed-case name could never match one.
+      expect(metricType).toBe(metricType.toLowerCase());
+      expect(metricType).not.toMatch(/\s/);
+      // MetricType.name is a ShortText column (100 characters).
+      expect(metricType.length).toBeLessThanOrEqual(100);
+      // "budget" is how the product names this, and the picker searches names.
+      expect(metricType).toContain(".budget.");
+    },
+  );
+
+  test.each(ALL_BUDGET_METRIC_TYPES)(
+    "%s is read from the immutable metric table, where the sweep writes it",
+    (metricType: SessionReplayBudgetMetricType) => {
+      expect(MutableMetricService.isMutableMetricName(metricType)).toBe(false);
+    },
+  );
+});
+
+describe("SessionReplayBudgetMetricTypeUtil.getAll", () => {
+  test("lists every member exactly once - the sweep and billing only see what is listed", () => {
+    const all: Array<SessionReplayBudgetMetricType> =
+      SessionReplayBudgetMetricTypeUtil.getAll();
+
+    expect([...all].sort()).toEqual([...ALL_BUDGET_METRIC_TYPES].sort());
+    expect(new Set(all).size).toBe(all.length);
+  });
+
+  test("lists the project series first", () => {
+    expect(SessionReplayBudgetMetricTypeUtil.getAll()).toEqual([
+      SessionReplayBudgetMetricType.ProjectDailyUsedBytes,
+      SessionReplayBudgetMetricType.ProjectDailyUsedPercent,
+      SessionReplayBudgetMetricType.ApplicationMonthlyUsedBytes,
+      SessionReplayBudgetMetricType.ApplicationMonthlyUsedPercent,
+    ]);
+  });
+
+  test("returns a fresh array, so one caller reordering it cannot reorder another's", () => {
+    const first: Array<SessionReplayBudgetMetricType> =
+      SessionReplayBudgetMetricTypeUtil.getAll();
+    first.reverse();
+
+    expect(SessionReplayBudgetMetricTypeUtil.getAll()[0]).toBe(
+      SessionReplayBudgetMetricType.ProjectDailyUsedBytes,
+    );
+  });
+});
+
+describe("SessionReplayBudgetMetricTypeUtil.isReservedMetricName", () => {
+  test.each(ALL_BUDGET_METRIC_TYPES)(
+    "reserves %s",
+    (metricType: SessionReplayBudgetMetricType) => {
+      expect(
+        SessionReplayBudgetMetricTypeUtil.isReservedMetricName(metricType),
+      ).toBe(true);
+    },
+  );
+
+  test("reserves the whole session replay namespace, not only today's names", () => {
+    expect(
+      SessionReplayBudgetMetricTypeUtil.isReservedMetricName(
+        "oneuptime.rum.session.replay.anything.new",
+      ),
+    ).toBe(true);
+  });
+
+  test("is case-insensitive, because ingest lowercases names onto the same series", () => {
+    expect(
+      SessionReplayBudgetMetricTypeUtil.isReservedMetricName(
+        "OneUptime.RUM.Session.Replay.Budget.Project.Daily.Used.Percent",
+      ),
+    ).toBe(true);
+  });
+
+  test.each([
+    "oneuptime.rum.application.id",
+    "oneuptime.llm.budget.percent.used",
+    "oneuptime.monitor.response.time",
+    "oneuptime.host.heartbeat",
+    "web_vital.lcp",
+    "session.replay.budget",
+    // No separator: a different namespace, however close.
+    "oneuptime.rum.session.replayed",
+    "oneuptime.rum.session.replay",
+    " oneuptime.rum.session.replay.budget.project.daily.used.bytes",
+  ])("leaves %p alone", (name: string) => {
+    expect(SessionReplayBudgetMetricTypeUtil.isReservedMetricName(name)).toBe(
+      false,
+    );
+  });
+
+  test("answers false for a missing name instead of throwing", () => {
+    expect(SessionReplayBudgetMetricTypeUtil.isReservedMetricName("")).toBe(
+      false,
+    );
+    expect(SessionReplayBudgetMetricTypeUtil.isReservedMetricName(null)).toBe(
+      false,
+    );
+    expect(
+      SessionReplayBudgetMetricTypeUtil.isReservedMetricName(undefined),
+    ).toBe(false);
+  });
+});
+
+describe("units", () => {
+  test("bytes series are 'By', which charts scale as bytes", () => {
+    for (const metricType of [
+      SessionReplayBudgetMetricType.ProjectDailyUsedBytes,
+      SessionReplayBudgetMetricType.ApplicationMonthlyUsedBytes,
+    ]) {
+      const unit: string =
+        SessionReplayBudgetMetricTypeUtil.getUnit(metricType);
+
+      expect(unit).toBe("By");
+      expect(MetricUnitUtil.getFamilyBaseUnit(unit)).toBe("B");
+    }
+  });
+
+  test("percent series are '%', never '1' (which the chart formatter would multiply by 100)", () => {
+    for (const metricType of [
+      SessionReplayBudgetMetricType.ProjectDailyUsedPercent,
+      SessionReplayBudgetMetricType.ApplicationMonthlyUsedPercent,
+    ]) {
+      const unit: string =
+        SessionReplayBudgetMetricTypeUtil.getUnit(metricType);
+
+      expect(unit).toBe("%");
+      expect(MetricUnitUtil.getFamilyBaseUnit(unit)).toBe("%");
+    }
+  });
+});
+
+describe("aggregation, titles, descriptions and scope", () => {
+  test.each(ALL_BUDGET_METRIC_TYPES)(
+    "%s aggregates with Max - Sum would multiply the shared project value",
+    (metricType: SessionReplayBudgetMetricType) => {
+      expect(
+        SessionReplayBudgetMetricTypeUtil.getAggregationType(metricType),
+      ).toBe(AggregationType.Max);
+    },
+  );
+
+  test("titles match the Health page's own labels", () => {
+    expect(
+      SessionReplayBudgetMetricTypeUtil.getTitle(
+        SessionReplayBudgetMetricType.ProjectDailyUsedBytes,
+      ),
+    ).toBe("Project Bytes Today");
+    expect(
+      SessionReplayBudgetMetricTypeUtil.getTitle(
+        SessionReplayBudgetMetricType.ProjectDailyUsedPercent,
+      ),
+    ).toBe("Project Daily Budget Used");
+    expect(
+      SessionReplayBudgetMetricTypeUtil.getTitle(
+        SessionReplayBudgetMetricType.ApplicationMonthlyUsedBytes,
+      ),
+    ).toBe("Application Bytes This Month");
+    expect(
+      SessionReplayBudgetMetricTypeUtil.getTitle(
+        SessionReplayBudgetMetricType.ApplicationMonthlyUsedPercent,
+      ),
+    ).toBe("Application Monthly Budget Used");
+  });
+
+  test.each(ALL_BUDGET_METRIC_TYPES)(
+    "%s has a catalog description that says how often it is written and that zero is not",
+    (metricType: SessionReplayBudgetMetricType) => {
+      const description: string =
+        SessionReplayBudgetMetricTypeUtil.getDescription(metricType);
+
+      expect(description.length).toBeGreaterThan(80);
+      expect(description).toContain(
+        `every ${SESSION_REPLAY_BUDGET_METRIC_INTERVAL_MINUTES} minutes`,
+      );
+      /*
+       * "Usage", not the value: a percent point goes out with its bytes point
+       * even when it rounds down to 0.00.
+       */
+      expect(description).toContain("while usage is above zero");
+    },
+  );
+
+  test("the project series warn against Sum, and say which applications carry them", () => {
+    for (const metricType of ALL_BUDGET_METRIC_TYPES) {
+      const description: string =
+        SessionReplayBudgetMetricTypeUtil.getDescription(metricType);
+      const projectScoped: boolean =
+        SessionReplayBudgetMetricTypeUtil.isProjectScoped(metricType);
+
+      expect(description.includes("never Sum")).toBe(projectScoped);
+      expect(
+        description.includes(
+          "every application that records (session replay on)",
+        ),
+      ).toBe(projectScoped);
+    }
+  });
+
+  /*
+   * The crossing upload is refused but stays counted, so the bytes were not
+   * all "let through" - they are what the limit was charged.
+   */
+  test("the daily bytes are what the limit was charged, not what was let through", () => {
+    const description: string =
+      SessionReplayBudgetMetricTypeUtil.getDescription(
+        SessionReplayBudgetMetricType.ProjectDailyUsedBytes,
+      );
+
+    expect(description).toContain("counted against the project's daily limit");
+    expect(description).not.toContain("let through");
+  });
+
+  test("the percent descriptions say what 100 means and that the value is rounded down", () => {
+    for (const metricType of [
+      SessionReplayBudgetMetricType.ProjectDailyUsedPercent,
+      SessionReplayBudgetMetricType.ApplicationMonthlyUsedPercent,
+    ]) {
+      const description: string =
+        SessionReplayBudgetMetricTypeUtil.getDescription(metricType);
+
+      expect(description).toContain("rounded down to 0.01");
+      expect(description).toContain("At 100 or more");
+    }
+  });
+
+  test("the monthly descriptions say the series only exists with a budget", () => {
+    for (const metricType of [
+      SessionReplayBudgetMetricType.ApplicationMonthlyUsedBytes,
+      SessionReplayBudgetMetricType.ApplicationMonthlyUsedPercent,
+    ]) {
+      expect(
+        SessionReplayBudgetMetricTypeUtil.getDescription(metricType),
+      ).toContain("only for applications with a monthly budget");
+    }
+  });
+
+  test("only the daily series are project-scoped", () => {
+    expect(
+      ALL_BUDGET_METRIC_TYPES.filter(
+        (metricType: SessionReplayBudgetMetricType) => {
+          return SessionReplayBudgetMetricTypeUtil.isProjectScoped(metricType);
+        },
+      ).sort(),
+    ).toEqual(
+      [
+        SessionReplayBudgetMetricType.ProjectDailyUsedBytes,
+        SessionReplayBudgetMetricType.ProjectDailyUsedPercent,
+      ].sort(),
+    );
+  });
+});
+
+describe("every lookup resolves for every member and refuses an unknown one", () => {
+  const lookups: Array<{
+    name: string;
+    run: (metricType: SessionReplayBudgetMetricType) => unknown;
+  }> = [
+    {
+      name: "getTitle",
+      run: (metricType: SessionReplayBudgetMetricType): unknown => {
+        return SessionReplayBudgetMetricTypeUtil.getTitle(metricType);
+      },
+    },
+    {
+      name: "getDescription",
+      run: (metricType: SessionReplayBudgetMetricType): unknown => {
+        return SessionReplayBudgetMetricTypeUtil.getDescription(metricType);
+      },
+    },
+    {
+      name: "getUnit",
+      run: (metricType: SessionReplayBudgetMetricType): unknown => {
+        return SessionReplayBudgetMetricTypeUtil.getUnit(metricType);
+      },
+    },
+    {
+      name: "getAggregationType",
+      run: (metricType: SessionReplayBudgetMetricType): unknown => {
+        return SessionReplayBudgetMetricTypeUtil.getAggregationType(metricType);
+      },
+    },
+    {
+      name: "isProjectScoped",
+      run: (metricType: SessionReplayBudgetMetricType): unknown => {
+        return SessionReplayBudgetMetricTypeUtil.isProjectScoped(metricType);
+      },
+    },
+  ];
+
+  test.each(lookups)(
+    "$name",
+    (lookup: {
+      name: string;
+      run: (metricType: SessionReplayBudgetMetricType) => unknown;
+    }) => {
+      for (const metricType of ALL_BUDGET_METRIC_TYPES) {
+        expect(lookup.run(metricType)).not.toBeUndefined();
+      }
+
+      expect(() => {
+        return lookup.run(UNKNOWN_METRIC_TYPE);
+      }).toThrow("Invalid SessionReplayBudgetMetricType value");
+    },
+  );
+});
+
+describe("attribute keys and cadence", () => {
+  test("use the bare keys the other internal metrics use", () => {
+    expect(SESSION_REPLAY_BUDGET_METRIC_PROJECT_ID_ATTRIBUTE).toBe("projectId");
+    expect(SESSION_REPLAY_BUDGET_METRIC_RUM_APPLICATION_ID_ATTRIBUTE).toBe(
+      "rumApplicationId",
+    );
+    expect(SESSION_REPLAY_BUDGET_METRIC_RUM_APPLICATION_NAME_ATTRIBUTE).toBe(
+      "rumApplicationName",
+    );
+  });
+
+  test("the sweep posts every five minutes", () => {
+    // The alert templates' 15-minute window is three of these.
+    expect(SESSION_REPLAY_BUDGET_METRIC_INTERVAL_MINUTES).toBe(5);
+  });
+});

package/Types/AI/ResourceAiAccessApi.ts

@@ -0,0 +1,140 @@
+import AiResourceType from "../ResourceAiAgent/AiResourceType";
+import { ResourceAiAccessStatus } from "../ResourceAiAgent/ResourceAiAccess";
+
+/*
+ * The dashboard-facing calls behind an infrastructure resource's AI pages
+ * (AI → Insights and AI → AI agent) for every resource a resource AI agent
+ * serves — Common/Server/API/ResourceAiAccessAPI.ts. Everything else on
+ * those pages is ordinary CRUD on the resource model (the investigation
+ * switch, the remediation mode, the command allowlist).
+ *
+ * Every route is POST under /api and takes a ResourceAiAccessRequest body.
+ */
+export const RESOURCE_AI_ACCESS_STATUS_PATH: string =
+  "/resource-ai-access/status";
+export const RESOURCE_AI_ACCESS_TEST_PATH: string = "/resource-ai-access/test";
+export const RESOURCE_AI_ACCESS_RESET_AGENT_PATH: string =
+  "/resource-ai-access/reset-agent";
+export const RESOURCE_AI_ACCESS_INSIGHTS_PATH: string =
+  "/resource-ai-access/insights";
+
+export interface ResourceAiAccessRequest {
+  // An AiResourceType value (an agent alias such as "docker" is accepted too).
+  resourceType: AiResourceType | string;
+  resourceId: string;
+}
+
+/*
+ * POST /resource-ai-access/test runs the type's test commands
+ * (AI_RESOURCE_TYPE_INFO[type].testCommands) through the resource's AI agent
+ * and answers with one of these per command it ran — it stops at the first
+ * that did not succeed.
+ */
+export interface ResourceAiAccessTestCommandResult {
+  command: string;
+  succeeded: boolean;
+  exitCode: number | null;
+  // Redacted and capped, the way every AI resource command's output is.
+  output: string;
+  errorMessage: string | null;
+}
+
+export interface ResourceAiAccessTestResponse {
+  ok: boolean;
+  message: string;
+  results: Array<ResourceAiAccessTestCommandResult>;
+  // The status after the test (it may have changed "Last verified").
+  status: ResourceAiAccessStatus;
+}
+
+// POST /resource-ai-access/reset-agent.
+export interface ResourceAiAccessResetAgentResponse {
+  ok: boolean;
+  message: string;
+  status?: ResourceAiAccessStatus | undefined;
+}
+
+/*
+ * POST /resource-ai-access/insights: what OneUptime AI investigated and
+ * changed on one resource, as summaries. Nothing here carries command
+ * output, a prompt or a command plan: the route is readable by everyone who
+ * may read the resource, a wider audience than the AI runs, suggestions and
+ * jobs it summarises. So an investigation whose incident or alert the
+ * caller cannot read is left out, a TL;DR is there only with a readable
+ * subject (or, for a run with none, for a caller who may read AIRun), and a
+ * fix's rationale only for a caller who may read that suggestion.
+ */
+
+// How many investigations, and how many fixes, the route returns (newest).
+export const RESOURCE_AI_INSIGHTS_LIMIT: number = 25;
+
+// The window commandCounts covers.
+export const RESOURCE_AI_INSIGHTS_COMMAND_WINDOW_IN_DAYS: number = 30;
+
+// How much of a fix's rationale the route returns.
+export const RESOURCE_AI_INSIGHTS_RATIONALE_MAX_LENGTH: number = 300;
+
+/*
+ * One investigation that concerns the resource: it ran a command on it
+ * through the resource's AI agent, or it investigated an incident or alert
+ * linked to it.
+ */
+export interface ResourceAiInsightInvestigation {
+  aiRunId: string;
+  // AIRunStatus.
+  status?: string | undefined;
+  analysisTldr?: string | undefined;
+  // ISO dates.
+  createdAt?: string | undefined;
+  completedAt?: string | undefined;
+  incident?:
+    | {
+        id: string;
+        title?: string | undefined;
+        number?: number | undefined;
+      }
+    | undefined;
+  alert?:
+    | {
+        id: string;
+        title?: string | undefined;
+      }
+    | undefined;
+}
+
+/*
+ * One fix AI proposed or ran on the resource: a round the resource's own
+ * AI remediation setting produced (AutoRemediationSuggestion.resourceType /
+ * resourceId), or any suggestion whose commands ran on the resource.
+ */
+export interface ResourceAiInsightFix {
+  id: string;
+  // AutoRemediationSuggestionStatus.
+  status?: string | undefined;
+  // AutoRemediationExecutionMode.
+  executionMode?: string | undefined;
+  // AutoRemediationSuggestionType.
+  suggestionType?: string | undefined;
+  // The first RESOURCE_AI_INSIGHTS_RATIONALE_MAX_LENGTH characters.
+  rationale?: string | undefined;
+  createdAt?: string | undefined;
+  approvedAt?: string | undefined;
+  incidentId?: string | undefined;
+  alertId?: string | undefined;
+}
+
+export interface ResourceAiInsights {
+  resourceType: AiResourceType;
+  resourceId: string;
+  investigations: Array<ResourceAiInsightInvestigation>;
+  fixes: Array<ResourceAiInsightFix>;
+  /*
+   * Commands AI ran on the resource through its AI agent in the last
+   * RESOURCE_AI_INSIGHTS_COMMAND_WINDOW_IN_DAYS days, by kind. The AI agent
+   * page's "Test connection" checks are not counted.
+   */
+  commandCounts: {
+    investigation: number;
+    remediation: number;
+  };
+}

package/Types/AI/ResourceAiAccessPermissions.ts

@@ -0,0 +1,126 @@
+import Permission, { PermissionHelper } from "../Permission";
+import AiResourceType, {
+  AI_RESOURCE_TYPE_INFO,
+} from "../ResourceAiAgent/AiResourceType";
+import { ResourceAiRemediationMode } from "../ResourceAiAgent/ResourceAiAccess";
+
+/*
+ * Who may change what OneUptime AI is allowed to do on an infrastructure
+ * resource reached through a resource AI agent (a Docker, Podman or Docker
+ * Swarm host, a Proxmox cluster, a VMware vCenter, a Ceph cluster, a
+ * database server or a host), and the words the server and the dashboard
+ * use for it.
+ *
+ * Kept apart from Types/ResourceAiAgent, which the resource AI agent carries
+ * a byte-identical copy of and which therefore stays free of the permission
+ * catalog.
+ */
+
+/*
+ * Who may LOOSEN a resource's AI access: turn AI fixes on (any move up from
+ * Off, Ask for approval included) or give them more autonomy (Automatic,
+ * Bypass approval), add a command allowlist pattern, and reset the
+ * resource's AI agent. A resource's AI mode does the job of a FullAuto
+ * AutoRemediationRule without a rule row, so it takes the same set a
+ * Kubernetes cluster's AI access takes (KUBERNETES_AI_ACCESS_ADMIN_
+ * PERMISSIONS — a Common test pins the two together).
+ *
+ * Tightening (Off, moving down, removing allowlist patterns or clearing the
+ * list) and the investigation switch stay open to anyone who may edit the
+ * resource: making AI do less never needs more privilege than the resource
+ * itself.
+ */
+export const RESOURCE_AI_ACCESS_ADMIN_PERMISSIONS: Array<Permission> = [
+  Permission.ProjectOwner,
+  Permission.ProjectAdmin,
+  Permission.EditAutoRemediationRule,
+];
+
+/*
+ * How each resource type is named inside a sentence ("on this Docker host",
+ * "on this database server"). AI_RESOURCE_TYPE_INFO's displayName starts
+ * every name with a capital, which reads wrong mid-sentence for the two
+ * types whose name is a common noun.
+ */
+const RESOURCE_SENTENCE_NAMES: Readonly<Record<AiResourceType, string>> = {
+  [AiResourceType.DockerHost]: "Docker host",
+  [AiResourceType.PodmanHost]: "Podman host",
+  [AiResourceType.DockerSwarmCluster]: "Docker Swarm cluster",
+  [AiResourceType.ProxmoxCluster]: "Proxmox cluster",
+  [AiResourceType.VMwareVCenter]: "VMware vCenter",
+  [AiResourceType.CephCluster]: "Ceph cluster",
+  [AiResourceType.DatabaseServer]: "database server",
+  [AiResourceType.Host]: "host",
+};
+
+export function getResourceSentenceName(resourceType: AiResourceType): string {
+  return RESOURCE_SENTENCE_NAMES[resourceType] || "resource";
+}
+
+// The name of the resource type's AI agent, for sentences ("the Docker AI agent").
+export function getResourceAgentName(resourceType: AiResourceType): string {
+  return AI_RESOURCE_TYPE_INFO[resourceType]?.agentDisplayName || "AI agent";
+}
+
+/*
+ * The AI agent page's short name for each remediation mode, used on the
+ * resource feed and in messages — the same words a Kubernetes cluster's
+ * page uses.
+ */
+export const RESOURCE_AI_REMEDIATION_MODE_LABELS: Readonly<
+  Record<ResourceAiRemediationMode, string>
+> = {
+  [ResourceAiRemediationMode.Disabled]: "Off",
+  [ResourceAiRemediationMode.RequireApproval]: "Ask for approval",
+  [ResourceAiRemediationMode.Automatic]: "Automatic",
+  [ResourceAiRemediationMode.BypassApproval]: "Bypass approval",
+};
+
+/*
+ * One valid allowlist entry per resource type — a change that needs
+ * approval unless allowlisted — shown as the example in the refusal of a
+ * malformed allowlist and usable as the dashboard field's placeholder. A
+ * Common test checks each one against the resource command policy.
+ */
+export const RESOURCE_AI_ALLOWLIST_EXAMPLES: Readonly<
+  Record<AiResourceType, string>
+> = {
+  [AiResourceType.DockerHost]: "docker stop web",
+  [AiResourceType.PodmanHost]: "docker stop web",
+  [AiResourceType.DockerSwarmCluster]:
+    "docker service update --image nginx:1.27 web",
+  [AiResourceType.ProxmoxCluster]:
+    "pvesh create /nodes/pve1/qemu/100/status/shutdown",
+  [AiResourceType.VMwareVCenter]: "govc vm.power -off web-01",
+  [AiResourceType.CephCluster]: "ceph osd out 3",
+  [AiResourceType.DatabaseServer]: "db terminate-session 12345",
+  [AiResourceType.Host]: "systemctl stop nginx",
+};
+
+/*
+ * The refusal for a caller who tried to make AI do more on a resource
+ * without one of RESOURCE_AI_ACCESS_ADMIN_PERMISSIONS: what needs them, who
+ * has them, and what stays open to every editor of the resource.
+ */
+export function getResourceAiAccessAdminRefusal(
+  resourceType: AiResourceType,
+): string {
+  const name: string = getResourceSentenceName(resourceType);
+
+  return `You need one of these permissions to let OneUptime AI do more on a ${name} (turn AI fixes on or give them more autonomy, or add command allowlist patterns): ${PermissionHelper.getPermissionTitles(
+    RESOURCE_AI_ACCESS_ADMIN_PERMISSIONS,
+  ).join(
+    ", ",
+  )}. Anyone who may edit the ${name} can still turn AI fixes off or down to Ask for approval, and remove allowlist patterns.`;
+}
+
+// The refusal for a caller who may not reset the resource's AI agent.
+export function getResourceAiAgentResetRefusal(
+  resourceType: AiResourceType,
+): string {
+  return `You need one of these permissions to reset this ${getResourceSentenceName(
+    resourceType,
+  )}'s ${getResourceAgentName(resourceType)}: ${PermissionHelper.getPermissionTitles(
+    RESOURCE_AI_ACCESS_ADMIN_PERMISSIONS,
+  ).join(", ")}.`;
+}