@oneuptime/common 11.3.25 → 11.3.26

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,
+    };
+  },
+};

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

@@ -0,0 +1,204 @@
+import Incident from "../../../../Models/DatabaseModels/Incident";
+import { JSONObject } from "../../../../Types/JSON";
+import ObjectID from "../../../../Types/ObjectID";
+import Permission from "../../../../Types/Permission";
+import SortOrder from "../../../../Types/BaseDatabase/SortOrder";
+import { AIChatCitationTargetType } from "../../../../Types/AI/AIChatTypes";
+import IncidentService from "../../../Services/IncidentService";
+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 Incident 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 Incident().getReadPermissions();
+    }
+    return cachedReadPermissions;
+  };
+
+export const QueryIncidentsTool: ObservabilityTool = {
+  name: "query_incidents",
+  description:
+    "Query incidents in this project. Returns the most recent incidents with their current state and severity. Pass incidentId to get full details of one incident.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      incidentId: {
+        type: "string",
+        description: "Get one incident by its ID (includes description).",
+      },
+      createdWithinHours: {
+        type: "number",
+        description:
+          "Only incidents created within this many hours (default 168 = 7 days, max 720).",
+      },
+      limit: {
+        type: "number",
+        description: "Maximum incidents to return (default 10, max 25).",
+      },
+    },
+  },
+  get requiredPermissions(): Array<Permission> {
+    return resolveReadPermissions();
+  },
+  execute: async (
+    args: JSONObject,
+    ctx: ToolContext,
+  ): Promise<ToolExecutionResult> => {
+    const incidentId: ObjectID | undefined = ToolArgs.getObjectID(
+      args,
+      "incidentId",
+    );
+
+    if (incidentId) {
+      const incident: Incident | null = await IncidentService.findOneById({
+        id: incidentId,
+        select: {
+          _id: true,
+          title: true,
+          description: true,
+          incidentNumber: true,
+          createdAt: true,
+          currentIncidentState: {
+            name: true,
+          },
+          incidentSeverity: {
+            name: true,
+          },
+        },
+        props: ctx.props,
+      });
+
+      const rows: Array<JSONObject> = incident
+        ? [
+            {
+              id: incident.id?.toString(),
+              incidentNumber: incident.incidentNumber,
+              title: incident.title,
+              description: incident.description,
+              state: incident.currentIncidentState?.name,
+              severity: incident.incidentSeverity?.name,
+              createdAt: incident.createdAt,
+            },
+          ]
+        : [];
+
+      const serialized: SerializedResult =
+        ToolResultSerializer.serializeRows(rows);
+
+      return {
+        dataForLlm: serialized.text,
+        rowCount: serialized.rowCount,
+        citationLabel: `Incident ${incident?.incidentNumber ? `#${incident.incidentNumber}` : incidentId.toString()}`,
+        citationTarget: {
+          type: AIChatCitationTargetType.IncidentView,
+          params: { incidentId: incidentId.toString() },
+        },
+        redactionCount: serialized.redactionCount,
+        isTruncated: serialized.isTruncated,
+        widget:
+          rows.length > 0
+            ? WidgetBuilder.incidentList({
+                title: `Incident #${incident?.incidentNumber ?? ""}`.trim(),
+                items: rows,
+                link: {
+                  type: AIChatCitationTargetType.IncidentView,
+                  params: { incidentId: incidentId.toString() },
+                },
+              })
+            : undefined,
+      };
+    }
+
+    const createdWithinHours: number = ToolArgs.getNumber(
+      args,
+      "createdWithinHours",
+      { defaultValue: 168, min: 1, max: 720 },
+    );
+    const limit: number = ToolArgs.getNumber(args, "limit", {
+      defaultValue: 10,
+      min: 1,
+      max: 25,
+    });
+
+    const endTime: Date = OneUptimeDate.getCurrentDate();
+    const startTime: Date = OneUptimeDate.addRemoveHours(
+      endTime,
+      -1 * createdWithinHours,
+    );
+
+    const incidents: Array<Incident> = await IncidentService.findBy({
+      query: {
+        createdAt: QueryHelper.inBetween(startTime, endTime),
+      },
+      select: {
+        _id: true,
+        title: true,
+        incidentNumber: true,
+        createdAt: true,
+        currentIncidentState: {
+          name: true,
+        },
+        incidentSeverity: {
+          name: true,
+        },
+      },
+      sort: {
+        createdAt: SortOrder.Descending,
+      },
+      limit: limit,
+      skip: 0,
+      props: ctx.props,
+    });
+
+    const rows: Array<JSONObject> = incidents.map((incident: Incident) => {
+      return {
+        id: incident.id?.toString(),
+        incidentNumber: incident.incidentNumber,
+        title: incident.title,
+        state: incident.currentIncidentState?.name,
+        severity: incident.incidentSeverity?.name,
+        createdAt: incident.createdAt,
+      };
+    });
+
+    const serialized: SerializedResult =
+      ToolResultSerializer.serializeRows(rows);
+
+    return {
+      dataForLlm: serialized.text,
+      rowCount: serialized.rowCount,
+      citationLabel: `Incidents, last ${createdWithinHours}h (${serialized.rowCount} found)`,
+      citationTarget: {
+        type: AIChatCitationTargetType.Incidents,
+      },
+      redactionCount: serialized.redactionCount,
+      isTruncated: serialized.isTruncated,
+      widget:
+        rows.length > 0
+          ? WidgetBuilder.incidentList({
+              title: `Incidents (${rows.length})`,
+              description: `Created in the last ${createdWithinHours}h`,
+              items: rows,
+              link: { type: AIChatCitationTargetType.Incidents },
+            })
+          : undefined,
+    };
+  },
+};