@oneuptime/common 12.0.32 → 12.0.33

package/Server/Services/StatusPagePrivateUserService.ts

@@ -1,6 +1,8 @@
 import DatabaseConfig from "../DatabaseConfig";
+import { EncryptionSecret } from "../EnvironmentConfig";
 import CreateBy from "../Types/Database/CreateBy";
-import { OnCreate } from "../Types/Database/Hooks";
+import UpdateBy from "../Types/Database/UpdateBy";
+import { OnCreate, OnUpdate } from "../Types/Database/Hooks";
 import logger from "../Utils/Logger";
 import DatabaseService from "./DatabaseService";
 import MailService from "./MailService";
@@ -13,6 +15,9 @@ import Protocol from "../../Types/API/Protocol";
 import URL from "../../Types/API/URL";
 import OneUptimeDate from "../../Types/Date";
 import EmailTemplateType from "../../Types/Email/EmailTemplateType";
+import LIMIT_MAX from "../../Types/Database/LimitMax";
+import Email from "../../Types/Email";
+import HashedString from "../../Types/HashedString";
 import BadDataException from "../../Types/Exception/BadDataException";
 import ObjectID from "../../Types/ObjectID";
 import StatusPage from "../../Models/DatabaseModels/StatusPage";
@@ -55,17 +60,112 @@ export class Service extends DatabaseService<Model> {
     };
   }
 
+  /**
+   * Kill any outstanding password-reset link for a status page user whose
+   * email address is about to change.
+   *
+   * Same invariant, and the same reasoning, as
+   * `UserService.expirePasswordResetTokensForEmailChange`: the link is a
+   * bearer credential addressed to one mailbox, and `/status-page-api/
+   * reset-password` finds the row by token hash and status page alone, never
+   * by the address the link was mailed to. Left unexpired, a link sent to the
+   * old address keeps working against the account at its new one.
+   *
+   * This path is worth closing even though a status page user cannot edit
+   * their own email: project admins can (the column carries `update` for
+   * ProjectAdmin and StatusPageAdmin), and `StatusPageSCIM.ts` rewrites it
+   * from the directory. "Move this subscriber to their new address" is the
+   * same rescue action, done by somebody else on the user's behalf, and it has
+   * to invalidate old links for the same reason.
+   *
+   * Cleared before the write, and only for rows whose address actually
+   * changes, so a SCIM push that re-sends an unchanged address does not
+   * invalidate a reset link the user is part-way through using.
+   */
+  @CaptureSpan()
+  protected override async onBeforeUpdate(
+    updateBy: UpdateBy<Model>,
+  ): Promise<OnUpdate<Model>> {
+    if (updateBy.data.email) {
+      const newEmail: string = (updateBy.data.email as Email)
+        .toString()
+        .toLowerCase();
+
+      const existingUsers: Array<Model> = await this.findBy({
+        query: updateBy.query,
+        select: {
+          _id: true,
+          email: true,
+        },
+        props: updateBy.props,
+        limit: LIMIT_MAX,
+        skip: 0,
+      });
+
+      for (const user of existingUsers) {
+        if (!user.id) {
+          continue;
+        }
+
+        /*
+         * A row whose `email` did not come back is treated as changed -- that
+         * only happens when the caller could not read the column, and on a
+         * credential the safe assumption is the one that expires the token.
+         */
+        const currentEmail: string | undefined = user.email
+          ?.toString()
+          .toLowerCase();
+
+        if (currentEmail === newEmail) {
+          continue;
+        }
+
+        await this.updateOneById({
+          id: user.id,
+          data: {
+            resetPasswordToken: null!,
+            resetPasswordExpires: null!,
+          },
+          props: {
+            isRoot: true,
+            ignoreHooks: true,
+          },
+        });
+      }
+    }
+
+    return {
+      updateBy: updateBy,
+      carryForward: null,
+    };
+  }
+
   @CaptureSpan()
   protected override async onCreateSuccess(
     _onCreate: OnCreate<Model>,
     createdItem: Model,
   ): Promise<Model> {
-    // send email to the user.
+    /*
+     * The invite link doubles as this user's first password-reset link, so the
+     * column has to hold what `/status-page-api/reset-password` looks rows up
+     * by: the SHA-256 of the token, never the token itself. That endpoint
+     * hashes whatever the link carried and queries by the digest, so a raw
+     * token stored here matches nothing and the welcome link is dead on
+     * arrival -- and it would also leave a working bearer credential sitting
+     * in the database in plaintext.
+     *
+     * Same split as `/status-page-api/forgot-password`: the digest is
+     * persisted, the raw token is only ever mailed.
+     */
     const token: string = ObjectID.generate().toString();
+    const hashedToken: string = await HashedString.hashValue(
+      token,
+      EncryptionSecret,
+    );
     await this.updateOneById({
       id: createdItem.id!,
       data: {
-        resetPasswordToken: token,
+        resetPasswordToken: hashedToken,
         resetPasswordExpires: OneUptimeDate.getOneDayAfter(),
       },
       props: {

package/Server/Services/UserNotificationEmailRollupBatchService.ts

@@ -0,0 +1,78 @@
+import CreateBy from "../Types/Database/CreateBy";
+import DeleteBy from "../Types/Database/DeleteBy";
+import UpdateBy from "../Types/Database/UpdateBy";
+import { OnCreate, OnDelete, OnUpdate } from "../Types/Database/Hooks";
+import DatabaseService from "./DatabaseService";
+import CaptureSpan from "../Utils/Telemetry/CaptureSpan";
+import { ROLLUP_BATCH_RETENTION_DAYS } from "../Utils/EmailRollup/EmailRollupConstants";
+import Model from "../../Models/DatabaseModels/UserNotificationEmailRollupBatch";
+import NotAuthorizedException from "../../Types/Exception/NotAuthorizedException";
+
+/*
+ * The rollup claim ledger. Root only in every direction: an insert here is
+ * what wins an epoch, so a caller who could create one could stop the next
+ * rollup being sent, and one who could delete one could make it be sent
+ * twice.
+ *
+ * Retention is set UNCONDITIONALLY, deliberately unlike EmailLogService,
+ * which only registers its retention when billing is enabled. The
+ * HardDelete:HardDeleteOlderItemsInDatabase cron iterates every service in
+ * the Services array with no billing check, so a gated call would simply
+ * never prune on a self-hosted install.
+ *
+ * Thirty days rather than the items' seven: a batch row is the record of how
+ * many notifications one email replaced, which is the number the whole
+ * feature is judged on, and it is one row per flush rather than one per
+ * notification. Pruning it cannot orphan anything, because rollupBatchId on
+ * the item table is deliberately a bare column with no foreign key.
+ */
+export class Service extends DatabaseService<Model> {
+  public constructor() {
+    super(Model);
+    this.hardDeleteItemsOlderThanInDays(
+      "createdAt",
+      ROLLUP_BATCH_RETENTION_DAYS,
+    );
+  }
+
+  @CaptureSpan()
+  protected override async onBeforeCreate(
+    createBy: CreateBy<Model>,
+  ): Promise<OnCreate<Model>> {
+    if (!createBy.props.isRoot) {
+      throw new NotAuthorizedException(
+        "Notification email rollup batches are claimed by the flush worker only.",
+      );
+    }
+
+    return { createBy, carryForward: null };
+  }
+
+  @CaptureSpan()
+  protected override async onBeforeUpdate(
+    updateBy: UpdateBy<Model>,
+  ): Promise<OnUpdate<Model>> {
+    if (!updateBy.props.isRoot) {
+      throw new NotAuthorizedException(
+        "Notification email rollup batches are claimed by the flush worker only.",
+      );
+    }
+
+    return { updateBy, carryForward: null };
+  }
+
+  @CaptureSpan()
+  protected override async onBeforeDelete(
+    deleteBy: DeleteBy<Model>,
+  ): Promise<OnDelete<Model>> {
+    if (!deleteBy.props.isRoot) {
+      throw new NotAuthorizedException(
+        "Notification email rollup batches are claimed by the flush worker only.",
+      );
+    }
+
+    return { deleteBy, carryForward: null };
+  }
+}
+
+export default new Service();

package/Server/Services/UserNotificationEmailRollupItemService.ts

@@ -0,0 +1,79 @@
+import CreateBy from "../Types/Database/CreateBy";
+import DeleteBy from "../Types/Database/DeleteBy";
+import UpdateBy from "../Types/Database/UpdateBy";
+import { OnCreate, OnDelete, OnUpdate } from "../Types/Database/Hooks";
+import DatabaseService from "./DatabaseService";
+import CaptureSpan from "../Utils/Telemetry/CaptureSpan";
+import { ROLLUP_ITEM_RETENTION_DAYS } from "../Utils/EmailRollup/EmailRollupConstants";
+import Model from "../../Models/DatabaseModels/UserNotificationEmailRollupItem";
+import NotAuthorizedException from "../../Types/Exception/NotAuthorizedException";
+
+/*
+ * The owner-email rollup queue and volume ledger. Root only in every
+ * direction: a pending row is the thing that makes a deferred notification
+ * eventually arrive, so nothing outside the notification write path and the
+ * flush sweep may insert, edit or remove one.
+ *
+ * Retention is set UNCONDITIONALLY, deliberately unlike EmailLogService,
+ * which only registers its retention when billing is enabled. The
+ * HardDelete:HardDeleteOlderItemsInDatabase cron iterates every service in
+ * the Services array and honours whatever retention it declares, with no
+ * billing check anywhere in the loop - so gating the call on IsBillingEnabled
+ * would leave a self-hosted install accumulating one row per owner email
+ * forever, which for the exact customer this feature exists for is thousands
+ * of rows a day.
+ *
+ * Seven days is chosen against the two things that read the table: the burst
+ * counter, which looks back BURST_WINDOW_MINUTES, and a human answering "what
+ * flooded this inbox last week".
+ */
+export class Service extends DatabaseService<Model> {
+  public constructor() {
+    super(Model);
+    this.hardDeleteItemsOlderThanInDays(
+      "createdAt",
+      ROLLUP_ITEM_RETENTION_DAYS,
+    );
+  }
+
+  @CaptureSpan()
+  protected override async onBeforeCreate(
+    createBy: CreateBy<Model>,
+  ): Promise<OnCreate<Model>> {
+    if (!createBy.props.isRoot) {
+      throw new NotAuthorizedException(
+        "Notification email rollup items are written by the notification pipeline only.",
+      );
+    }
+
+    return { createBy, carryForward: null };
+  }
+
+  @CaptureSpan()
+  protected override async onBeforeUpdate(
+    updateBy: UpdateBy<Model>,
+  ): Promise<OnUpdate<Model>> {
+    if (!updateBy.props.isRoot) {
+      throw new NotAuthorizedException(
+        "Notification email rollup items are written by the notification pipeline only.",
+      );
+    }
+
+    return { updateBy, carryForward: null };
+  }
+
+  @CaptureSpan()
+  protected override async onBeforeDelete(
+    deleteBy: DeleteBy<Model>,
+  ): Promise<OnDelete<Model>> {
+    if (!deleteBy.props.isRoot) {
+      throw new NotAuthorizedException(
+        "Notification email rollup items are written by the notification pipeline only.",
+      );
+    }
+
+    return { deleteBy, carryForward: null };
+  }
+}
+
+export default new Service();

package/Server/Services/UserNotificationEmailRollupSettingService.ts

@@ -0,0 +1,113 @@
+import DatabaseService from "./DatabaseService";
+import CreateBy from "../Types/Database/CreateBy";
+import { OnCreate } from "../Types/Database/Hooks";
+import CaptureSpan from "../Utils/Telemetry/CaptureSpan";
+import Model from "../../Models/DatabaseModels/UserNotificationEmailRollupSetting";
+import BadDataException from "../../Types/Exception/BadDataException";
+import ObjectID from "../../Types/ObjectID";
+
+/*
+ * The escape hatch from owner-email burst rollup, one row per (user, project).
+ *
+ * The read below is the ONLY place the preference is consulted, and it is
+ * deliberately not cached. A cache would mean a person who has just clicked
+ * "send me every email immediately" keeps getting batched mail for the length
+ * of the TTL - which is precisely the complaint the toggle exists to answer,
+ * reproduced by the mechanism meant to serve it. The query is a single indexed
+ * row on a table with at most one row per project member, on a path that
+ * already runs a dozen queries, and the write path only reaches it when it is
+ * about to DEFER - never on the common below-the-threshold send.
+ */
+export class Service extends DatabaseService<Model> {
+  public constructor() {
+    super(Model);
+  }
+
+  /*
+   * True when this person's owner notification emails may be coalesced.
+   *
+   * Absent row means enabled. Rollup ships on by default with no backfill, so
+   * almost nobody has a row here; treating "no row" as anything other than the
+   * default would make the feature depend on data that does not exist.
+   *
+   * This does NOT swallow errors. The one caller reads it inside the write
+   * path's fail-open catch, which turns any failure into an immediate send -
+   * the same direction this method's `false` means, and the same direction
+   * every other failure in that path takes.
+   */
+  @CaptureSpan()
+  public async isRollupEnabledForUser(data: {
+    userId: ObjectID;
+    projectId: ObjectID;
+  }): Promise<boolean> {
+    const setting: Model | null = await this.findOneBy({
+      query: {
+        userId: data.userId,
+        projectId: data.projectId,
+      },
+      select: {
+        isEnabled: true,
+      },
+      props: {
+        isRoot: true,
+      },
+    });
+
+    if (!setting) {
+      return true;
+    }
+
+    /*
+     * Only an explicit false opts out. A row whose isEnabled somehow arrived
+     * NULL - a hand-written insert, a column added ahead of its default - is
+     * not an opt-out, because opting somebody out of individual emails is the
+     * change that needs to have been asked for.
+     */
+    return setting.isEnabled !== false;
+  }
+
+  @CaptureSpan()
+  protected override async onBeforeCreate(
+    createBy: CreateBy<Model>,
+  ): Promise<OnCreate<Model>> {
+    if (!createBy.data.projectId) {
+      throw new BadDataException("projectId is required");
+    }
+
+    if (!createBy.data.userId) {
+      throw new BadDataException("userId is required");
+    }
+
+    /*
+     * One row per person per project. The page creates lazily on the first
+     * toggle, so a double click or two open tabs would otherwise leave two
+     * rows and make findOneBy's answer depend on which one it happened to
+     * pick. There is no unique index behind this check - the same
+     * check-then-create shape UserNotificationSettingService.onBeforeCreate
+     * already uses - so it narrows the window rather than closing it; the read
+     * above tolerates a duplicate because both rows say the same thing in
+     * every flow the UI can produce.
+     */
+    const existingCount: number = (
+      await this.countBy({
+        query: {
+          projectId: createBy.data.projectId,
+          userId: createBy.data.userId,
+        },
+        props: {
+          isRoot: true,
+        },
+      })
+    ).toNumber();
+
+    if (existingCount > 0) {
+      throw new BadDataException(
+        "An email rollup setting already exists for this user in this project.",
+      );
+    }
+
+    return { createBy, carryForward: null };
+  }
+}
+
+export default new Service();

package/Server/Services/UserNotificationSettingService.ts

@@ -3,7 +3,6 @@ import { OnCreate } from "../Types/Database/Hooks";
 import logger from "../Utils/Logger";
 import CallService from "./CallService";
 import DatabaseService from "./DatabaseService";
-import MailService from "./MailService";
 import ProjectCallSMSConfigService from "./ProjectCallSMSConfigService";
 import SmsService from "./SmsService";
 import TeamMemberService from "./TeamMemberService";
@@ -51,6 +50,7 @@ import {
   WorkspaceMessageBlock,
   WorkspacePayloadMarkdown,
 } from "../../Types/Workspace/WorkspaceMessagePayload";
+import EmailRollupWriter from "../Utils/EmailRollup/EmailRollupWriter";
 import CaptureSpan from "../Utils/Telemetry/CaptureSpan";
 import { appendRecipientToWhatsAppMessage } from "../Utils/WhatsAppTemplateUtil";
 
@@ -76,6 +76,16 @@ export class Service extends DatabaseService<UserNotificationSetting> {
      */
     whatsAppMessage?: WhatsAppMessagePayload | undefined;
     telegramMessage?: TelegramMessagePayload | undefined;
+    /*
+     * Bypasses burst coalescing for this send, before any rollup bookkeeping
+     * runs. Some producers reuse another family's event type: the SLA-breach
+     * job at App/FeatureSet/Workers/Jobs/IncidentSla/CheckSlaBreaches.ts sends
+     * under EmailTemplateType.IncidentOwnerResourceCreated at :265 and reuses
+     * SEND_INCIDENT_CREATED_OWNER_NOTIFICATION at :286, so the event type
+     * alone cannot express that this particular message is urgent. Only a
+     * caller knows that, so only a caller can say so.
+     */
+    forceImmediate?: boolean | undefined;
     incidentId?: ObjectID | undefined;
     alertId?: ObjectID | undefined;
     alertEpisodeId?: ObjectID | undefined;
@@ -140,33 +150,60 @@ export class Service extends DatabaseService<UserNotificationSetting> {
         });
 
         for (const userEmail of userEmails) {
-          MailService.sendMail(
-            {
-              ...data.emailEnvelope,
-              toEmail: userEmail.email!,
-            },
-            {
+          /*
+           * The one seam where an owner email can be held back. Below the
+           * burst threshold this is byte-for-byte the send that was here
+           * before - same envelope, same correlation ids, still
+           * fire-and-forget inside the writer - and above it the message is
+           * queued for a rollup instead of dropped. Awaited, unlike the raw
+           * send it replaces, because the queue row has to exist before this
+           * method returns; the writer itself never awaits MailService.
+           *
+           * data.emailEnvelope is passed by reference and is never mutated by
+           * the writer, which the Telegram fallback below and the Slack /
+           * Microsoft Teams bodies further down depend on: all three
+           * synthesise their message from data.emailEnvelope.subject.
+           *
+           * Guarded even though sendOrRollup is written not to throw. The send
+           * it replaces was fire-and-forget, so one bad address could never
+           * cost another address its email - let alone cost this notification
+           * its SMS, call, push, Telegram, workspace and webhook deliveries
+           * further down. Awaiting reintroduces that possibility; this catch
+           * takes it back out.
+           */
+          try {
+            await EmailRollupWriter.sendOrRollup({
               projectId: data.projectId,
-              incidentId: data.incidentId,
-              alertId: data.alertId,
-              alertEpisodeId: data.alertEpisodeId,
-              incidentEpisodeId: data.incidentEpisodeId,
-              monitorId: data.monitorId,
-              scheduledMaintenanceId: data.scheduledMaintenanceId,
-              statusPageId: data.statusPageId,
-              statusPageAnnouncementId: data.statusPageAnnouncementId,
               userId: data.userId,
-              teamId: data.teamId,
-              // OnCall-related fields
-              onCallPolicyId: data.onCallPolicyId,
-              onCallPolicyEscalationRuleId: data.onCallPolicyEscalationRuleId,
-              onCallDutyPolicyExecutionLogTimelineId:
-                data.onCallDutyPolicyExecutionLogTimelineId,
-              onCallScheduleId: data.onCallScheduleId,
-            },
-          ).catch((err: Error) => {
+              toEmail: userEmail.email!,
+              eventType: data.eventType,
+              emailEnvelope: data.emailEnvelope,
+              mailOptions: {
+                projectId: data.projectId,
+                incidentId: data.incidentId,
+                alertId: data.alertId,
+                alertEpisodeId: data.alertEpisodeId,
+                incidentEpisodeId: data.incidentEpisodeId,
+                monitorId: data.monitorId,
+                scheduledMaintenanceId: data.scheduledMaintenanceId,
+                statusPageId: data.statusPageId,
+                statusPageAnnouncementId: data.statusPageAnnouncementId,
+                userId: data.userId,
+                teamId: data.teamId,
+                // OnCall-related fields
+                onCallPolicyId: data.onCallPolicyId,
+                onCallPolicyEscalationRuleId: data.onCallPolicyEscalationRuleId,
+                onCallDutyPolicyExecutionLogTimelineId:
+                  data.onCallDutyPolicyExecutionLogTimelineId,
+                onCallScheduleId: data.onCallScheduleId,
+              },
+              ...(data.forceImmediate !== undefined && {
+                forceImmediate: data.forceImmediate,
+              }),
+            });
+          } catch (err) {
             logger.error(err);
-          });
+          }
         }
       }
 

package/Server/Services/UserService.ts

@@ -353,6 +353,13 @@ export class Service extends DatabaseService<Model> {
       carryForward = users;
     }
 
+    if (updateBy.data.email) {
+      await this.expirePasswordResetTokensForEmailChange({
+        newEmail: updateBy.data.email as Email,
+        existingUsers: carryForward,
+      });
+    }
+
     /*
      * There used to be a guard here refusing to set `enableTwoFactorAuth` on
      * an account with no verified authenticator, on the grounds that doing so
@@ -412,6 +419,94 @@ export class Service extends DatabaseService<Model> {
     return { updateBy, carryForward: carryForward };
   }
 
+  /**
+   * Kill any outstanding password-reset link for every account whose email
+   * address this update is about to change.
+   *
+   * A reset link is a bearer credential addressed to ONE mailbox: holding it
+   * proves only that somebody could read mail sent to the address the account
+   * had when the link was minted. Move the account to a different address and
+   * that proof is about a mailbox the account no longer uses, so the link has
+   * to die with the address it was sent to.
+   *
+   * Without this, changing your email is not the account-recovery step that
+   * users -- and our own "You have changed your email" mail -- take it to be:
+   *
+   *   1. An attacker who can read the victim's mailbox requests a password
+   *      reset and does NOT spend the link. Nothing about the account looks
+   *      wrong, because nothing has changed yet.
+   *   2. The victim notices the mailbox is compromised and moves the account
+   *      to an address the attacker cannot read. This is exactly the advice
+   *      they would be given, and they now believe they are safe.
+   *   3. The attacker spends the link from step 1. `/reset-password` finds the
+   *      row BY TOKEN HASH ALONE -- it never looks at the email address -- so
+   *      it happily sets a new password on the account at its NEW address, and
+   *      the victim is locked out of an account they had just rescued.
+   *
+   * Cleared BEFORE the email is written rather than afterwards in
+   * `onUpdateSuccess`, so there is no instant in which the new address is
+   * committed while a link mailed to the old one is still redeemable. The
+   * price of that ordering is that an email update which subsequently fails
+   * has still burned a pending link, and the user has to request another one.
+   * For a credential that is the right way round.
+   *
+   * Only rows whose address actually CHANGES are touched. Directory syncs
+   * rewrite `email` with the value it already has on every push (see
+   * `App/FeatureSet/Identity/API/SCIM.ts`, which updates whenever either the
+   * email or the name is present), and clearing on those would let an
+   * unrelated SCIM run invalidate a reset link the user is part-way through
+   * using.
+   *
+   * A row that came back with no `email` at all is treated as changed. That
+   * happens when the caller could not read the column, and on a credential the
+   * safe assumption is the one that expires the token.
+   *
+   * NOTE: this runs from `onBeforeUpdate`, so an email write made with
+   * `ignoreHooks: true` would slip past it. Nothing does that today -- the
+   * dashboard, the SCIM endpoints and the admin API all go through the hooks
+   * -- and any new caller that writes `email` hook-free has to clear these two
+   * columns itself.
+   */
+  @CaptureSpan()
+  private async expirePasswordResetTokensForEmailChange(data: {
+    newEmail: Email;
+    existingUsers: Array<Model>;
+  }): Promise<void> {
+    const newEmail: string = data.newEmail.toString().toLowerCase();
+
+    for (const user of data.existingUsers) {
+      if (!user.id) {
+        continue;
+      }
+
+      const currentEmail: string | undefined = user.email
+        ?.toString()
+        .toLowerCase();
+
+      if (currentEmail === newEmail) {
+        continue;
+      }
+
+      await this.updateOneById({
+        id: user.id,
+        data: {
+          resetPasswordToken: null!,
+          resetPasswordExpires: null!,
+        },
+        /*
+         * Root because `resetPasswordToken` is declared with `update: []` --
+         * no permission can write it -- and hook-free because this IS the
+         * update hook; re-entering it would have this write go looking for an
+         * email change of its own.
+         */
+        props: {
+          isRoot: true,
+          ignoreHooks: true,
+        },
+      });
+    }
+  }
+
   @CaptureSpan()
   protected override async onBeforeDelete(
     deleteBy: DeleteBy<Model>,

package/Server/Types/Database/QueryHelper.ts

@@ -656,7 +656,7 @@ export default class QueryHelper {
   }
 
   @CaptureSpan()
-  public static greaterThan<T extends number | Date>(
+  public static greaterThan<T extends number | Date | ObjectID>(
     value: T,
   ): FindWhereProperty<any> {
     const rid: string = Text.generateRandomText(10);
@@ -665,7 +665,7 @@ export default class QueryHelper {
         return `(${alias} > :${rid})`;
       },
       {
-        [rid]: value,
+        [rid]: value instanceof ObjectID ? value.toString() : value,
       },
     ) as FindWhereProperty<any>;
   }

package/Server/Utils/AI/Chat/ObservabilityChatPrompt.ts

@@ -61,14 +61,25 @@ function buildEntityContextGuidance(context: AIChatPageContext): string {
   }
 }
 
+/*
+ * Per-area guidance for list and explorer pages. This text is the only
+ * capability claim in the request that is scoped to the page the user is on,
+ * so the model weighs it against the tool schemas — which means it must never
+ * describe a tool as NARROWER than it is. It previously summarised
+ * query_incidents as "recent incidents, or one by incidentId", and the model
+ * paraphrased that back as "I have no tool to list active incidents, give me
+ * an incidentId" on the very page whose own suggested prompt card asks
+ * "which incidents are currently active or unresolved?". Every affordance an
+ * area page's suggested prompts depend on has to be named here.
+ */
 function buildAreaContextGuidance(type: AIChatPageContextType): string {
   switch (type) {
     case AIChatPageContextType.IncidentsList:
-      return `the incidents list. Questions about "these incidents" or incident activity are answered with query_incidents (recent incidents, or one by incidentId) and search_incidents (free-text search over past incidents).`;
+      return `the incidents list. Questions about "these incidents" or incident activity are answered with query_incidents: pass state="active" to list every incident that is unresolved RIGHT NOW (this drops the time window, so incidents opened weeks ago are still returned), leave state unset for recent activity in a window, or pass incidentId for one incident's full details. search_incidents does free-text search over past incidents.`;
     case AIChatPageContextType.AlertsList:
-      return `the alerts list. Questions about alert activity are answered with query_alerts.`;
+      return `the alerts list. Questions about alert activity are answered with query_alerts: pass state="active" to list every alert that is unresolved RIGHT NOW regardless of age, leave state unset for recent activity in a window, or pass alertId for one alert's full details.`;
     case AIChatPageContextType.MonitorsList:
-      return `the monitors list. Questions about monitors and their status are answered with query_monitors.`;
+      return `the monitors list. Questions about monitors and their status are answered with query_monitors: pass problemsOnly=true to list the monitors that are NOT operational right now, or monitorId for one monitor's details and its recent status timeline.`;
     case AIChatPageContextType.ScheduledMaintenanceList:
       return `the scheduled maintenance list. Questions about maintenance windows are answered with query_scheduled_maintenance (past, ongoing and upcoming events; one event by scheduledMaintenanceId). recent_changes also merges maintenance into a chronological feed alongside other changes.`;
     case AIChatPageContextType.LogsExplorer: