@oneuptime/common 11.3.25 → 11.3.28

package/Server/Utils/AI/Toolbox/AlertWriteTools.ts

@@ -0,0 +1,174 @@
+import Alert from "../../../../Models/DatabaseModels/Alert";
+import { JSONObject } from "../../../../Types/JSON";
+import ObjectID from "../../../../Types/ObjectID";
+import Permission from "../../../../Types/Permission";
+import BadDataException from "../../../../Types/Exception/BadDataException";
+import { AIChatCitationTargetType } from "../../../../Types/AI/AIChatTypes";
+import AlertService from "../../../Services/AlertService";
+import ToolResultSerializer, { SerializedResult } from "./Serializer";
+import WidgetBuilder from "./WidgetBuilder";
+import {
+  ObservabilityTool,
+  ToolArgs,
+  ToolContext,
+  ToolExecutionResult,
+} from "./ToolTypes";
+
+/*
+ * Derived from the model ACL so the tool gate can never drift from RBAC.
+ * Resolved lazily rather than at module load: this module is pulled in through
+ * the service import graph before the Alert model class is fully wired up, so
+ * calling a model method at import time throws a circular-dependency
+ * TypeError. By the time a tool actually executes, every module is loaded.
+ */
+let cachedUpdatePermissions: Array<Permission> | null = null;
+const resolveUpdatePermissions: () => Array<Permission> =
+  (): Array<Permission> => {
+    if (!cachedUpdatePermissions) {
+      cachedUpdatePermissions = new Alert().getUpdatePermissions();
+    }
+    return cachedUpdatePermissions;
+  };
+
+async function changeAlertStateTool(data: {
+  args: JSONObject;
+  ctx: ToolContext;
+  verb: "acknowledge" | "resolve";
+}): Promise<ToolExecutionResult> {
+  const { args, ctx, verb } = data;
+
+  const alertId: ObjectID | undefined = ToolArgs.getObjectID(args, "alertId");
+  if (!alertId) {
+    throw new BadDataException(
+      "alertId is required. Use query_alerts to find it first.",
+    );
+  }
+
+  const userId: ObjectID | undefined = ctx.props.userId;
+  if (!userId) {
+    throw new BadDataException(
+      "No authenticated user in context; cannot change the alert.",
+    );
+  }
+
+  // Confirm the alert is visible to this user under their RBAC.
+  const alert: Alert | null = await AlertService.findOneById({
+    id: alertId,
+    select: {
+      _id: true,
+      alertNumber: true,
+      title: true,
+    },
+    props: ctx.props,
+  });
+
+  if (!alert) {
+    throw new BadDataException(
+      "Alert not found (or you do not have access to it).",
+    );
+  }
+
+  if (verb === "acknowledge") {
+    await AlertService.acknowledgeAlert(alertId, userId);
+  } else {
+    await AlertService.resolveAlert(alertId, userId);
+  }
+
+  const newStateName: string =
+    verb === "acknowledge" ? "Acknowledged" : "Resolved";
+
+  const alertIdString: string = alertId.toString();
+
+  const serialized: SerializedResult = ToolResultSerializer.serializeRows([
+    {
+      id: alertIdString,
+      alertNumber: alert.alertNumber,
+      title: alert.title,
+      newState: newStateName,
+    },
+  ]);
+
+  return {
+    dataForLlm: `Alert #${alert.alertNumber} ("${alert.title}") is now ${newStateName}.\n${serialized.text}`,
+    rowCount: 1,
+    citationLabel: `${newStateName} alert #${alert.alertNumber}`,
+    citationTarget: {
+      type: AIChatCitationTargetType.AlertView,
+      params: { alertId: alertIdString },
+    },
+    redactionCount: serialized.redactionCount,
+    isTruncated: false,
+    widget: WidgetBuilder.resourceCard({
+      title: `Alert ${newStateName.toLowerCase()}`,
+      resourceType: "Alert",
+      heading: `#${alert.alertNumber} · ${alert.title}`,
+      subheading: `Now ${newStateName}`,
+      fields: [
+        { label: "Number", value: `#${alert.alertNumber ?? ""}` },
+        { label: "State", value: newStateName },
+      ],
+      link: {
+        type: AIChatCitationTargetType.AlertView,
+        params: { alertId: alertIdString },
+      },
+    }),
+  };
+}
+
+export const AcknowledgeAlertTool: ObservabilityTool = {
+  name: "acknowledge_alert",
+  description:
+    "Acknowledge an alert (move it to the acknowledged state) by its alertId. Find the alertId with query_alerts first.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      alertId: {
+        type: "string",
+        description: "The alert's ID (required).",
+      },
+    },
+    required: ["alertId"],
+  },
+  get requiredPermissions(): Array<Permission> {
+    return resolveUpdatePermissions();
+  },
+  isMutation: true,
+  buildActionTitle: (args: JSONObject): string => {
+    return `Acknowledge alert ${ToolArgs.getString(args, "alertId") || ""}`.trim();
+  },
+  execute: async (
+    args: JSONObject,
+    ctx: ToolContext,
+  ): Promise<ToolExecutionResult> => {
+    return changeAlertStateTool({ args, ctx, verb: "acknowledge" });
+  },
+};
+
+export const ResolveAlertTool: ObservabilityTool = {
+  name: "resolve_alert",
+  description:
+    "Resolve an alert (move it to the resolved state) by its alertId. Find the alertId with query_alerts first.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      alertId: {
+        type: "string",
+        description: "The alert's ID (required).",
+      },
+    },
+    required: ["alertId"],
+  },
+  get requiredPermissions(): Array<Permission> {
+    return resolveUpdatePermissions();
+  },
+  isMutation: true,
+  buildActionTitle: (args: JSONObject): string => {
+    return `Resolve alert ${ToolArgs.getString(args, "alertId") || ""}`.trim();
+  },
+  execute: async (
+    args: JSONObject,
+    ctx: ToolContext,
+  ): Promise<ToolExecutionResult> => {
+    return changeAlertStateTool({ args, ctx, verb: "resolve" });
+  },
+};

package/Server/Utils/AI/Toolbox/ContextTools.ts

@@ -0,0 +1,189 @@
+import MetricType from "../../../../Models/DatabaseModels/MetricType";
+import Service from "../../../../Models/DatabaseModels/Service";
+import SortOrder from "../../../../Types/BaseDatabase/SortOrder";
+import BadDataException from "../../../../Types/Exception/BadDataException";
+import { JSONObject } from "../../../../Types/JSON";
+import Permission from "../../../../Types/Permission";
+import TelemetryType from "../../../../Types/Telemetry/TelemetryType";
+import MetricTypeService from "../../../Services/MetricTypeService";
+import ServiceService from "../../../Services/ServiceService";
+import TelemetryAttributeService from "../../../Services/TelemetryAttributeService";
+import QueryHelper from "../../../Types/Database/QueryHelper";
+import ToolResultSerializer, { SerializedResult } from "./Serializer";
+import {
+  ObservabilityTool,
+  ToolArgs,
+  ToolContext,
+  ToolExecutionResult,
+} from "./ToolTypes";
+
+const CONTEXT_READ_PERMISSIONS: Array<Permission> = [
+  Permission.ProjectOwner,
+  Permission.ProjectAdmin,
+  Permission.ProjectMember,
+  Permission.Viewer,
+  Permission.TelemetryAdmin,
+  Permission.TelemetryMember,
+  Permission.TelemetryViewer,
+];
+
+export const LookupContextTool: ObservabilityTool = {
+  name: "lookup_context",
+  description:
+    "Discover what exists in this project so other tools can be called with exact identifiers: telemetry services (name → ID), metric names, and attribute keys for logs/traces/metrics. ALWAYS resolve a service name to its ID here before filtering other tools by service.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      type: {
+        type: "string",
+        enum: ["services", "metricNames", "attributeKeys"],
+        description: "What to look up (required).",
+      },
+      nameSearch: {
+        type: "string",
+        description: "Filter results whose name contains this text.",
+      },
+      telemetryType: {
+        type: "string",
+        enum: ["Log", "Trace", "Metric", "Exception"],
+        description:
+          "For attributeKeys lookups: which signal's attribute keys to list.",
+      },
+    },
+    required: ["type"],
+  },
+  requiredPermissions: CONTEXT_READ_PERMISSIONS,
+  execute: async (
+    args: JSONObject,
+    ctx: ToolContext,
+  ): Promise<ToolExecutionResult> => {
+    const lookupType: string | undefined = ToolArgs.getString(args, "type");
+    const nameSearch: string | undefined = ToolArgs.getString(
+      args,
+      "nameSearch",
+    );
+
+    if (lookupType === "services") {
+      const services: Array<Service> = await ServiceService.findBy({
+        query: nameSearch
+          ? {
+              name: QueryHelper.search(nameSearch),
+            }
+          : {},
+        select: {
+          _id: true,
+          name: true,
+        },
+        sort: {
+          name: SortOrder.Ascending,
+        },
+        limit: 100,
+        skip: 0,
+        props: ctx.props,
+      });
+
+      const rows: Array<JSONObject> = services.map((service: Service) => {
+        return {
+          id: service.id?.toString(),
+          name: service.name,
+        };
+      });
+
+      const serialized: SerializedResult =
+        ToolResultSerializer.serializeRows(rows);
+
+      return {
+        dataForLlm: serialized.text,
+        rowCount: serialized.rowCount,
+        citationLabel: `Telemetry services (${serialized.rowCount} found)`,
+        citationTarget: undefined,
+        redactionCount: serialized.redactionCount,
+        isTruncated: serialized.isTruncated,
+      };
+    }
+
+    if (lookupType === "metricNames") {
+      const metricTypes: Array<MetricType> = await MetricTypeService.findBy({
+        query: nameSearch
+          ? {
+              name: QueryHelper.search(nameSearch),
+            }
+          : {},
+        select: {
+          name: true,
+        },
+        sort: {
+          name: SortOrder.Ascending,
+        },
+        limit: 200,
+        skip: 0,
+        props: ctx.props,
+      });
+
+      const rows: Array<JSONObject> = metricTypes.map(
+        (metricType: MetricType) => {
+          return {
+            name: metricType.name,
+          };
+        },
+      );
+
+      const serialized: SerializedResult =
+        ToolResultSerializer.serializeRows(rows);
+
+      return {
+        dataForLlm: serialized.text,
+        rowCount: serialized.rowCount,
+        citationLabel: `Metric names (${serialized.rowCount} found)`,
+        citationTarget: undefined,
+        redactionCount: serialized.redactionCount,
+        isTruncated: serialized.isTruncated,
+      };
+    }
+
+    if (lookupType === "attributeKeys") {
+      const telemetryTypeString: string =
+        ToolArgs.getString(args, "telemetryType") || "Log";
+
+      if (
+        !Object.values(TelemetryType).includes(
+          telemetryTypeString as TelemetryType,
+        )
+      ) {
+        throw new BadDataException(
+          `Invalid telemetryType: ${telemetryTypeString}`,
+        );
+      }
+
+      const attributes: Array<string> =
+        await TelemetryAttributeService.fetchAttributes({
+          projectId: ctx.projectId,
+          telemetryType: telemetryTypeString as TelemetryType,
+        });
+
+      const filtered: Array<string> = nameSearch
+        ? attributes.filter((attribute: string) => {
+            return attribute.toLowerCase().includes(nameSearch.toLowerCase());
+          })
+        : attributes;
+
+      const serialized: SerializedResult = ToolResultSerializer.serializeText(
+        filtered.slice(0, 200).join("\n"),
+        filtered.length,
+      );
+
+      return {
+        dataForLlm: serialized.text,
+        rowCount: serialized.rowCount,
+        citationLabel: `${telemetryTypeString} attribute keys (${filtered.length} found)`,
+        citationTarget: undefined,
+        redactionCount: serialized.redactionCount,
+        isTruncated: serialized.isTruncated,
+      };
+    }
+
+    throw new BadDataException(
+      `Invalid lookup type: ${lookupType}. Use one of: services, metricNames, attributeKeys.`,
+    );
+  },
+};

package/Server/Utils/AI/Toolbox/ExceptionTools.ts

@@ -0,0 +1,149 @@
+import TelemetryException from "../../../../Models/DatabaseModels/TelemetryException";
+import { JSONObject } from "../../../../Types/JSON";
+import Permission from "../../../../Types/Permission";
+import SortOrder from "../../../../Types/BaseDatabase/SortOrder";
+import { AIChatCitationTargetType } from "../../../../Types/AI/AIChatTypes";
+import TelemetryExceptionService from "../../../Services/TelemetryExceptionService";
+import QueryHelper from "../../../Types/Database/QueryHelper";
+import OneUptimeDate from "../../../../Types/Date";
+import ToolResultSerializer, { SerializedResult } from "./Serializer";
+import WidgetBuilder from "./WidgetBuilder";
+import {
+  ObservabilityTool,
+  ToolArgs,
+  ToolContext,
+  ToolExecutionResult,
+} from "./ToolTypes";
+
+/*
+ * Derived from the model ACL so the tool gate can never drift from RBAC.
+ * Resolved lazily rather than at module load: this module is pulled in through
+ * the service import graph before the TelemetryException model class is fully
+ * wired up, so calling a model method at import time throws a
+ * circular-dependency TypeError. By the time a tool actually executes, every
+ * module is loaded.
+ */
+let cachedReadPermissions: Array<Permission> | null = null;
+const resolveReadPermissions: () => Array<Permission> =
+  (): Array<Permission> => {
+    if (!cachedReadPermissions) {
+      cachedReadPermissions = new TelemetryException().getReadPermissions();
+    }
+    return cachedReadPermissions;
+  };
+
+export const TopExceptionsTool: ObservabilityTool = {
+  name: "top_exceptions",
+  description:
+    "Get the top exceptions (grouped by fingerprint) in this project, sorted by occurrence count. Includes first/last seen timestamps so you can tell if an exception is new or recurring.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      lastSeenWithinHours: {
+        type: "number",
+        description:
+          "Only exceptions last seen within this many hours (default 168 = 7 days, max 720).",
+      },
+      includeResolved: {
+        type: "boolean",
+        description: "Include resolved exceptions (default false).",
+      },
+      limit: {
+        type: "number",
+        description: "Maximum exception groups to return (default 10, max 25).",
+      },
+    },
+  },
+  get requiredPermissions(): Array<Permission> {
+    return resolveReadPermissions();
+  },
+  execute: async (
+    args: JSONObject,
+    ctx: ToolContext,
+  ): Promise<ToolExecutionResult> => {
+    const lastSeenWithinHours: number = ToolArgs.getNumber(
+      args,
+      "lastSeenWithinHours",
+      { defaultValue: 168, min: 1, max: 720 },
+    );
+    const includeResolved: boolean =
+      ToolArgs.getBoolean(args, "includeResolved") ?? false;
+    const limit: number = ToolArgs.getNumber(args, "limit", {
+      defaultValue: 10,
+      min: 1,
+      max: 25,
+    });
+
+    const since: Date = OneUptimeDate.addRemoveHours(
+      OneUptimeDate.getCurrentDate(),
+      -1 * lastSeenWithinHours,
+    );
+
+    const query: JSONObject = {
+      lastSeenAt: QueryHelper.greaterThanEqualTo(since),
+    };
+
+    if (!includeResolved) {
+      query["isResolved"] = false;
+    }
+
+    const exceptions: Array<TelemetryException> =
+      await TelemetryExceptionService.findBy({
+        query: query as never,
+        select: {
+          _id: true,
+          message: true,
+          exceptionType: true,
+          fingerprint: true,
+          occuranceCount: true,
+          firstSeenAt: true,
+          lastSeenAt: true,
+          isResolved: true,
+        },
+        sort: {
+          occuranceCount: SortOrder.Descending,
+        },
+        limit: limit,
+        skip: 0,
+        props: ctx.props,
+      });
+
+    const rows: Array<JSONObject> = exceptions.map(
+      (exception: TelemetryException) => {
+        return {
+          id: exception.id?.toString(),
+          type: exception.exceptionType,
+          message: exception.message,
+          occurrences: exception.occuranceCount,
+          firstSeenAt: exception.firstSeenAt,
+          lastSeenAt: exception.lastSeenAt,
+          isResolved: exception.isResolved,
+          fingerprint: exception.fingerprint,
+        };
+      },
+    );
+
+    const serialized: SerializedResult =
+      ToolResultSerializer.serializeRows(rows);
+
+    return {
+      dataForLlm: serialized.text,
+      rowCount: serialized.rowCount,
+      citationLabel: `Top exceptions, last ${lastSeenWithinHours}h (${serialized.rowCount} found)`,
+      citationTarget: {
+        type: AIChatCitationTargetType.Exceptions,
+      },
+      redactionCount: serialized.redactionCount,
+      isTruncated: serialized.isTruncated,
+      widget:
+        rows.length > 0
+          ? WidgetBuilder.exceptionList({
+              title: `Top exceptions (${rows.length})`,
+              description: `Last ${lastSeenWithinHours}h, by occurrence count`,
+              items: rows,
+              link: { type: AIChatCitationTargetType.Exceptions },
+            })
+          : undefined,
+    };
+  },
+};