@oneuptime/common 11.3.25 → 11.3.26

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

@@ -0,0 +1,350 @@
+import Incident from "../../../../Models/DatabaseModels/Incident";
+import IncidentSeverity from "../../../../Models/DatabaseModels/IncidentSeverity";
+import { JSONObject } from "../../../../Types/JSON";
+import ObjectID from "../../../../Types/ObjectID";
+import Permission from "../../../../Types/Permission";
+import BadDataException from "../../../../Types/Exception/BadDataException";
+import SortOrder from "../../../../Types/BaseDatabase/SortOrder";
+import { AIChatCitationTargetType } from "../../../../Types/AI/AIChatTypes";
+import IncidentService from "../../../Services/IncidentService";
+import IncidentSeverityService from "../../../Services/IncidentSeverityService";
+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 cachedCreatePermissions: Array<Permission> | null = null;
+const resolveCreatePermissions: () => Array<Permission> =
+  (): Array<Permission> => {
+    if (!cachedCreatePermissions) {
+      cachedCreatePermissions = new Incident().getCreatePermissions();
+    }
+    return cachedCreatePermissions;
+  };
+let cachedUpdatePermissions: Array<Permission> | null = null;
+const resolveUpdatePermissions: () => Array<Permission> =
+  (): Array<Permission> => {
+    if (!cachedUpdatePermissions) {
+      cachedUpdatePermissions = new Incident().getUpdatePermissions();
+    }
+    return cachedUpdatePermissions;
+  };
+
+/*
+ * Write tools mutate the project. They are gated twice: once by the tool's
+ * requiredPermissions (RBAC) and once by the conversation's permission mode
+ * (approval / auto-run / hidden in read-only). The user id used for the write
+ * is the requesting user's — taken from ctx.props, never a tool argument.
+ */
+
+export const CreateIncidentTool: ObservabilityTool = {
+  name: "create_incident",
+  description:
+    "Declare (create) a new incident in this project. Provide a clear title and a description of the problem. Optionally set the severity by name (must match an existing incident severity); otherwise the project's first-defined severity is used. Use this when the user asks you to open, declare or create an incident.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      title: {
+        type: "string",
+        description: "Short, specific incident title (required).",
+      },
+      description: {
+        type: "string",
+        description:
+          "Markdown description of what is happening, impact and any known cause.",
+      },
+      severityName: {
+        type: "string",
+        description:
+          "Name of an existing incident severity (e.g. 'SEV1', 'Critical'). Defaults to the project's first-defined severity.",
+      },
+    },
+    required: ["title"],
+  },
+  get requiredPermissions(): Array<Permission> {
+    return resolveCreatePermissions();
+  },
+  isMutation: true,
+  buildActionTitle: (args: JSONObject): string => {
+    return `Create incident: ${ToolArgs.getString(args, "title") || "Untitled"}`;
+  },
+  execute: async (
+    args: JSONObject,
+    ctx: ToolContext,
+  ): Promise<ToolExecutionResult> => {
+    const title: string | undefined = ToolArgs.getString(args, "title");
+    if (!title) {
+      throw new BadDataException("title is required to create an incident.");
+    }
+
+    const description: string = ToolArgs.getString(args, "description") || "";
+
+    const userId: ObjectID | undefined = ctx.props.userId;
+    if (!userId) {
+      throw new BadDataException(
+        "No authenticated user in context; cannot create an incident.",
+      );
+    }
+
+    const severities: Array<IncidentSeverity> =
+      await IncidentSeverityService.findBy({
+        query: {},
+        select: {
+          _id: true,
+          name: true,
+          order: true,
+        },
+        sort: {
+          order: SortOrder.Ascending,
+        },
+        limit: 50,
+        skip: 0,
+        props: ctx.props,
+      });
+
+    if (severities.length === 0) {
+      throw new BadDataException(
+        "No incident severities are configured for this project. Add one in Project Settings > Incidents > Severities first.",
+      );
+    }
+
+    let severity: IncidentSeverity = severities[0]!;
+    const severityName: string | undefined = ToolArgs.getString(
+      args,
+      "severityName",
+    );
+    if (severityName) {
+      const match: IncidentSeverity | undefined = severities.find(
+        (item: IncidentSeverity) => {
+          return item.name?.toLowerCase() === severityName.toLowerCase();
+        },
+      );
+      if (match) {
+        severity = match;
+      }
+    }
+
+    const incident: Incident = new Incident();
+    incident.projectId = ctx.projectId;
+    incident.title = title;
+    incident.description = description;
+    incident.incidentSeverityId = severity.id!;
+    incident.createdByUserId = userId;
+    incident.rootCause = "Incident created via the OneUptime AI copilot.";
+
+    // Created under the user's props so the model-layer RBAC applies too.
+    const created: Incident = await IncidentService.create({
+      data: incident,
+      props: ctx.props,
+    });
+
+    const incidentIdString: string = created.id!.toString();
+
+    const serialized: SerializedResult = ToolResultSerializer.serializeRows([
+      {
+        id: incidentIdString,
+        incidentNumber: created.incidentNumber,
+        title: title,
+        severity: severity.name,
+      },
+    ]);
+
+    return {
+      dataForLlm: `Successfully created incident #${created.incidentNumber} ("${title}", severity ${severity.name}).\n${serialized.text}`,
+      rowCount: 1,
+      citationLabel: `Created incident #${created.incidentNumber}`,
+      citationTarget: {
+        type: AIChatCitationTargetType.IncidentView,
+        params: { incidentId: incidentIdString },
+      },
+      redactionCount: serialized.redactionCount,
+      isTruncated: false,
+      widget: WidgetBuilder.resourceCard({
+        title: "Incident created",
+        resourceType: "Incident",
+        heading: `#${created.incidentNumber} · ${title}`,
+        subheading: severity.name ? `Severity: ${severity.name}` : undefined,
+        fields: [
+          { label: "Number", value: `#${created.incidentNumber ?? ""}` },
+          { label: "Severity", value: severity.name || "—" },
+          ...(description
+            ? [
+                {
+                  label: "Description",
+                  value:
+                    description.length > 200
+                      ? `${description.substring(0, 200)}…`
+                      : description,
+                },
+              ]
+            : []),
+        ],
+        link: {
+          type: AIChatCitationTargetType.IncidentView,
+          params: { incidentId: incidentIdString },
+        },
+      }),
+    };
+  },
+};
+
+async function changeIncidentStateTool(data: {
+  args: JSONObject;
+  ctx: ToolContext;
+  verb: "acknowledge" | "resolve";
+}): Promise<ToolExecutionResult> {
+  const { args, ctx, verb } = data;
+
+  const incidentId: ObjectID | undefined = ToolArgs.getObjectID(
+    args,
+    "incidentId",
+  );
+  if (!incidentId) {
+    throw new BadDataException(
+      "incidentId is required. Use query_incidents to find it first.",
+    );
+  }
+
+  const userId: ObjectID | undefined = ctx.props.userId;
+  if (!userId) {
+    throw new BadDataException(
+      "No authenticated user in context; cannot change the incident.",
+    );
+  }
+
+  /*
+   * Confirm the incident is visible to this user under their RBAC (the state
+   * change itself runs as root inside the service). This stops the tool from
+   * acting on incidents the user cannot see.
+   */
+  const incident: Incident | null = await IncidentService.findOneById({
+    id: incidentId,
+    select: {
+      _id: true,
+      incidentNumber: true,
+      title: true,
+    },
+    props: ctx.props,
+  });
+
+  if (!incident) {
+    throw new BadDataException(
+      "Incident not found (or you do not have access to it).",
+    );
+  }
+
+  if (verb === "acknowledge") {
+    await IncidentService.acknowledgeIncident(incidentId, userId);
+  } else {
+    await IncidentService.resolveIncident(incidentId, userId);
+  }
+
+  const newStateName: string =
+    verb === "acknowledge" ? "Acknowledged" : "Resolved";
+
+  const incidentIdString: string = incidentId.toString();
+
+  const serialized: SerializedResult = ToolResultSerializer.serializeRows([
+    {
+      id: incidentIdString,
+      incidentNumber: incident.incidentNumber,
+      title: incident.title,
+      newState: newStateName,
+    },
+  ]);
+
+  return {
+    dataForLlm: `Incident #${incident.incidentNumber} ("${incident.title}") is now ${newStateName}.\n${serialized.text}`,
+    rowCount: 1,
+    citationLabel: `${newStateName} incident #${incident.incidentNumber}`,
+    citationTarget: {
+      type: AIChatCitationTargetType.IncidentView,
+      params: { incidentId: incidentIdString },
+    },
+    redactionCount: serialized.redactionCount,
+    isTruncated: false,
+    widget: WidgetBuilder.resourceCard({
+      title: `Incident ${newStateName.toLowerCase()}`,
+      resourceType: "Incident",
+      heading: `#${incident.incidentNumber} · ${incident.title}`,
+      subheading: `Now ${newStateName}`,
+      fields: [
+        { label: "Number", value: `#${incident.incidentNumber ?? ""}` },
+        { label: "State", value: newStateName },
+      ],
+      link: {
+        type: AIChatCitationTargetType.IncidentView,
+        params: { incidentId: incidentIdString },
+      },
+    }),
+  };
+}
+
+export const AcknowledgeIncidentTool: ObservabilityTool = {
+  name: "acknowledge_incident",
+  description:
+    "Acknowledge an incident (move it to the acknowledged state) by its incidentId. Find the incidentId with query_incidents first.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      incidentId: {
+        type: "string",
+        description: "The incident's ID (required).",
+      },
+    },
+    required: ["incidentId"],
+  },
+  get requiredPermissions(): Array<Permission> {
+    return resolveUpdatePermissions();
+  },
+  isMutation: true,
+  buildActionTitle: (args: JSONObject): string => {
+    return `Acknowledge incident ${ToolArgs.getString(args, "incidentId") || ""}`.trim();
+  },
+  execute: async (
+    args: JSONObject,
+    ctx: ToolContext,
+  ): Promise<ToolExecutionResult> => {
+    return changeIncidentStateTool({ args, ctx, verb: "acknowledge" });
+  },
+};
+
+export const ResolveIncidentTool: ObservabilityTool = {
+  name: "resolve_incident",
+  description:
+    "Resolve an incident (move it to the resolved state) by its incidentId. Find the incidentId with query_incidents first.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      incidentId: {
+        type: "string",
+        description: "The incident's ID (required).",
+      },
+    },
+    required: ["incidentId"],
+  },
+  get requiredPermissions(): Array<Permission> {
+    return resolveUpdatePermissions();
+  },
+  isMutation: true,
+  buildActionTitle: (args: JSONObject): string => {
+    return `Resolve incident ${ToolArgs.getString(args, "incidentId") || ""}`.trim();
+  },
+  execute: async (
+    args: JSONObject,
+    ctx: ToolContext,
+  ): Promise<ToolExecutionResult> => {
+    return changeIncidentStateTool({ args, ctx, verb: "resolve" });
+  },
+};

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

@@ -0,0 +1,228 @@
+import { JSONObject } from "../../../../Types/JSON";
+import Permission, {
+  PermissionHelper,
+  UserPermission,
+} from "../../../../Types/Permission";
+import DatabaseCommonInteractionPropsUtil, {
+  PermissionType,
+} from "../../../../Types/BaseDatabase/DatabaseCommonInteractionPropsUtil";
+import { LLMToolDefinition } from "../../LLM/LLMService";
+import logger from "../../Logger";
+import {
+  ObservabilityTool,
+  ToolContext,
+  ToolExecutionResult,
+} from "./ToolTypes";
+import { QueryIncidentsTool } from "./IncidentTools";
+import { QueryAlertsTool } from "./AlertTools";
+import { QueryMonitorsTool } from "./MonitorTools";
+import { TopExceptionsTool } from "./ExceptionTools";
+import { LogHistogramTool, SearchLogsTool } from "./LogTools";
+import { QueryMetricsTool } from "./MetricTools";
+import { GetTraceTool, QueryTracesTool } from "./TraceTools";
+import { LookupContextTool } from "./ContextTools";
+import {
+  AcknowledgeIncidentTool,
+  CreateIncidentTool,
+  ResolveIncidentTool,
+} from "./IncidentWriteTools";
+import { AcknowledgeAlertTool, ResolveAlertTool } from "./AlertWriteTools";
+import AIChatPermissionMode from "../../../../Types/AI/AIChatPermissionMode";
+
+export interface ToolCallOutcome {
+  success: boolean;
+  /*
+   * What goes back to the LLM: serialized data, or an error envelope the
+   * model can self-correct from.
+   */
+  textForLlm: string;
+  result?: ToolExecutionResult | undefined;
+  errorMessage?: string | undefined;
+}
+
+const TOOL_EXECUTION_TIMEOUT_MS: number = 45 * 1000;
+
+/*
+ * The curated tool belt for AI features (chat today, the Investigation Engine
+ * later). Read tools wrap an existing deterministic query; write tools mutate
+ * the project (create/acknowledge/resolve). Every tool executes under the
+ * requesting user's permission props, and write tools are additionally gated by
+ * the conversation's permission mode (see ChatAgentRunner).
+ */
+export default class AIToolbox {
+  private static readonly tools: Array<ObservabilityTool> = [
+    LookupContextTool,
+    QueryIncidentsTool,
+    QueryAlertsTool,
+    QueryMonitorsTool,
+    TopExceptionsTool,
+    SearchLogsTool,
+    LogHistogramTool,
+    QueryMetricsTool,
+    QueryTracesTool,
+    GetTraceTool,
+    // Write tools (mutations). Gated by conversation permission mode.
+    CreateIncidentTool,
+    AcknowledgeIncidentTool,
+    ResolveIncidentTool,
+    AcknowledgeAlertTool,
+    ResolveAlertTool,
+  ];
+
+  public static getTools(): Array<ObservabilityTool> {
+    return this.tools;
+  }
+
+  // LLM tool definitions cached per permission mode (ReadOnly hides mutations).
+  private static llmToolDefinitionsByMode: Map<
+    AIChatPermissionMode,
+    Array<LLMToolDefinition>
+  > = new Map();
+
+  public static getToolByName(name: string): ObservabilityTool | undefined {
+    return this.tools.find((tool: ObservabilityTool) => {
+      return tool.name === name;
+    });
+  }
+
+  public static isMutationTool(name: string): boolean {
+    const tool: ObservabilityTool | undefined = this.getToolByName(name);
+    return Boolean(tool?.isMutation);
+  }
+
+  /*
+   * The tool definitions offered to the model for a given permission mode. In
+   * ReadOnly mode the mutating tools are withheld entirely, so the model never
+   * even proposes an action it isn't allowed to take.
+   */
+  public static getLlmToolDefinitions(
+    mode: AIChatPermissionMode,
+  ): Array<LLMToolDefinition> {
+    const cached: Array<LLMToolDefinition> | undefined =
+      this.llmToolDefinitionsByMode.get(mode);
+    if (cached) {
+      return cached;
+    }
+
+    const includeMutations: boolean = mode !== AIChatPermissionMode.ReadOnly;
+
+    const definitions: Array<LLMToolDefinition> = this.tools
+      .filter((tool: ObservabilityTool) => {
+        return includeMutations || !tool.isMutation;
+      })
+      .map((tool: ObservabilityTool) => {
+        return {
+          name: tool.name,
+          description: tool.description,
+          inputSchema: tool.inputSchema,
+        };
+      });
+
+    this.llmToolDefinitionsByMode.set(mode, definitions);
+    return definitions;
+  }
+
+  public static hasPermissionForTool(
+    tool: ObservabilityTool,
+    ctx: ToolContext,
+  ): boolean {
+    if (ctx.props.isRoot || ctx.props.isMasterAdmin) {
+      return true;
+    }
+
+    /*
+     * Fail closed on block permissions: if any of the tool's permissions is
+     * block-listed for this user, deny the tool outright. This is coarser
+     * than the label-scoped block filtering the model layer applies, but the
+     * raw-SQL aggregation tools have no model layer — this gate is their
+     * only authorization.
+     */
+    const blockedPermissions: Array<Permission> =
+      DatabaseCommonInteractionPropsUtil.getUserPermissions(
+        ctx.props,
+        PermissionType.Block,
+      ).map((userPermission: UserPermission) => {
+        return userPermission.permission;
+      });
+
+    if (
+      PermissionHelper.doesPermissionsIntersect(
+        blockedPermissions,
+        tool.requiredPermissions,
+      )
+    ) {
+      return false;
+    }
+
+    const userPermissions: Array<Permission> =
+      DatabaseCommonInteractionPropsUtil.getUserPermissions(
+        ctx.props,
+        PermissionType.Allow,
+      ).map((userPermission: UserPermission) => {
+        return userPermission.permission;
+      });
+
+    return PermissionHelper.doesPermissionsIntersect(
+      userPermissions,
+      tool.requiredPermissions,
+    );
+  }
+
+  public static async executeTool(data: {
+    name: string;
+    args: JSONObject;
+    ctx: ToolContext;
+  }): Promise<ToolCallOutcome> {
+    const tool: ObservabilityTool | undefined = this.getToolByName(data.name);
+
+    if (!tool) {
+      return {
+        success: false,
+        textForLlm: `Error: unknown tool "${data.name}". Available tools: ${this.tools
+          .map((availableTool: ObservabilityTool) => {
+            return availableTool.name;
+          })
+          .join(", ")}.`,
+        errorMessage: `Unknown tool: ${data.name}`,
+      };
+    }
+
+    if (!this.hasPermissionForTool(tool, data.ctx)) {
+      return {
+        success: false,
+        textForLlm: `Error: the current user does not have permission to use ${data.name}. Answer with the data you already have, and tell the user which permission is missing.`,
+        errorMessage: `Permission denied for tool: ${data.name}`,
+      };
+    }
+
+    try {
+      const result: ToolExecutionResult = await Promise.race([
+        tool.execute(data.args, data.ctx),
+        new Promise<never>(
+          (_resolve: unknown, reject: (err: Error) => void) => {
+            setTimeout(() => {
+              reject(new Error("Tool execution timed out."));
+            }, TOOL_EXECUTION_TIMEOUT_MS);
+          },
+        ),
+      ]);
+
+      return {
+        success: true,
+        textForLlm: result.dataForLlm,
+        result: result,
+      };
+    } catch (error) {
+      const message: string =
+        error instanceof Error ? error.message : String(error);
+
+      logger.error(`AI toolbox tool ${data.name} failed: ${message}`);
+
+      return {
+        success: false,
+        textForLlm: `Error executing ${data.name}: ${message}. Adjust the arguments and try again, or answer with the data you already have.`,
+        errorMessage: message,
+      };
+    }
+  }
+}