@oneuptime/common 11.4.0 → 11.4.1

package/Server/Utils/AI/Sentinel/IncidentInvestigationRunner.ts

@@ -23,7 +23,7 @@ import CaptureSpan from "../../Telemetry/CaptureSpan";
  * posts the result to the incident's feed.
  *
  * Built on the fire-and-forget async pattern already used throughout
- * IncidentService.onCreateSuccess. See Internal/Roadmap/AISentinelReliabilityBrain.md.
+ * IncidentService.onCreateSuccess. See Internal/Roadmap/AISentinelExecution.md.
  */
 export default class SentinelIncidentInvestigationRunner {
   /*

package/Server/Utils/AI/Sentinel/README.md

@@ -0,0 +1,10 @@
+# Sentinel — autonomous investigation engine
+
+Wake-on-signal AI SRE: when an incident or alert is created (and the project has opted in), Sentinel runs a read-only, budgeted, citation-minting investigation over the project's own telemetry and posts a root-cause analysis to the subject's feed, with a glass-box `AIRun`/`AIRunEvent` trail behind a live dashboard panel.
+
+- `SentinelInvestigationEngine.ts` — shared run lifecycle, budgets, persona, quiet-mode confidence gate
+- `IncidentInvestigationRunner.ts` / `AlertInvestigationRunner.ts` — per-subject context assembly + result posting
+- `IncidentPostmortemRunner.ts` — auto-draft postmortem when an incident resolves
+- `SentinelMemory.ts` — recurrence context from past resolved incidents (retrieval-only v1)
+
+**Roadmap & status:** [Internal/Roadmap/AISentinelExecution.md](../../../../../Internal/Roadmap/AISentinelExecution.md) (tracker — update it in the same PR when you change behavior here) and [Internal/Roadmap/AISentinelVision.md](../../../../../Internal/Roadmap/AISentinelVision.md) (strategy).

package/Server/Utils/Monitor/Criteria/APIRequestCriteria.ts

@@ -88,6 +88,50 @@ export default class APIRequestCriteria {
       });
     }
 
+    // check packet loss (Ping/IP monitors with multi-packet checks)
+    if (input.criteriaFilter.checkOn === CheckOn.PacketLossPercent) {
+      const packetLossPercent: number | undefined = (
+        input.dataToProcess as ProbeMonitorResponse
+      ).pingResponse?.packetLossPercent;
+
+      const value: Array<number> | number | undefined =
+        (overTimeValue as Array<number>) || packetLossPercent;
+
+      if (value === undefined) {
+        return null;
+      }
+
+      threshold = CompareCriteria.convertToNumber(threshold);
+
+      return CompareCriteria.compareCriteriaNumbers({
+        value: value,
+        threshold: threshold as number,
+        criteriaFilter: input.criteriaFilter,
+      });
+    }
+
+    // check jitter (Ping/IP monitors with multi-packet checks)
+    if (input.criteriaFilter.checkOn === CheckOn.Jitter) {
+      const jitterInMs: number | undefined = (
+        input.dataToProcess as ProbeMonitorResponse
+      ).pingResponse?.jitterInMs;
+
+      const value: Array<number> | number | undefined =
+        (overTimeValue as Array<number>) || jitterInMs;
+
+      if (value === undefined) {
+        return null;
+      }
+
+      threshold = CompareCriteria.convertToNumber(threshold);
+
+      return CompareCriteria.compareCriteriaNumbers({
+        value: value,
+        threshold: threshold as number,
+        criteriaFilter: input.criteriaFilter,
+      });
+    }
+
     //check response code
     if (
       input.criteriaFilter.checkOn === CheckOn.ResponseStatusCode &&

package/Server/Utils/Monitor/MonitorMetricUtil.ts

@@ -14,7 +14,9 @@ import BasicInfrastructureMetrics, {
 import Dictionary from "../../../Types/Dictionary";
 import { JSONObject } from "../../../Types/JSON";
 import CapturedMetric from "../../../Types/Monitor/CustomCodeMonitor/CapturedMetric";
+import HttpPhaseTimings from "../../../Types/Monitor/HttpPhaseTimings";
 import MonitorMetricType from "../../../Types/Monitor/MonitorMetricType";
+import PingMonitorResponse from "../../../Types/Monitor/PingMonitor/PingMonitorResponse";
 import ProbeMonitorResponse from "../../../Types/Probe/ProbeMonitorResponse";
 import ServerMonitorResponse from "../../../Types/Monitor/ServerMonitor/ServerMonitorResponse";
 import SyntheticMonitorResponse from "../../../Types/Monitor/SyntheticMonitors/SyntheticMonitorResponse";
@@ -23,8 +25,12 @@ import ObjectID from "../../../Types/ObjectID";
 import OneUptimeDate from "../../../Types/Date";
 
 export default class MonitorMetricUtil {
-  // Default retention in days if GlobalConfig is not set
-  private static readonly DEFAULT_RETENTION_DAYS: number = 1;
+  /*
+   * Default retention in days if GlobalConfig is not set. 30 days keeps
+   * enough history for trend analysis and evaluate-over-time criteria;
+   * one day made week-over-week charts impossible out of the box.
+   */
+  private static readonly DEFAULT_RETENTION_DAYS: number = 30;
 
   // Cached retention value to avoid querying GlobalConfig on every monitor check
   private static cachedRetentionDays: number | null = null;
@@ -883,6 +889,106 @@ export default class MonitorMetricUtil {
       metricNameServiceNameMap[MonitorMetricType.ResponseTime] = metricType;
     }
 
+    if ((data.dataToProcess as ProbeMonitorResponse).httpTimings) {
+      const httpTimings: HttpPhaseTimings = (
+        data.dataToProcess as ProbeMonitorResponse
+      ).httpTimings!;
+
+      const extraAttributes: JSONObject = {
+        probeId: (
+          data.dataToProcess as ProbeMonitorResponse
+        ).probeId.toString(),
+      };
+
+      const phaseMetrics: Array<{
+        metricName: MonitorMetricType;
+        value: number | undefined;
+        description: string;
+      }> = [
+        {
+          metricName: MonitorMetricType.DnsLookupTime,
+          value: httpTimings.dnsLookupInMs,
+          description: "DNS lookup time for this monitor",
+        },
+        {
+          metricName: MonitorMetricType.TcpConnectTime,
+          value: httpTimings.tcpConnectInMs,
+          description: "TCP connect time for this monitor",
+        },
+        {
+          metricName: MonitorMetricType.TlsHandshakeTime,
+          value: httpTimings.tlsHandshakeInMs,
+          description: "TLS handshake time for this monitor",
+        },
+        {
+          metricName: MonitorMetricType.TimeToFirstByte,
+          value: httpTimings.timeToFirstByteInMs,
+          description: "Time to first byte for this monitor",
+        },
+        {
+          metricName: MonitorMetricType.DownloadTime,
+          value: httpTimings.downloadInMs,
+          description: "Response download time for this monitor",
+        },
+      ];
+
+      for (const phaseMetric of phaseMetrics) {
+        await this.pushMonitorMetric({
+          projectId: data.projectId,
+          monitorId: data.monitorId,
+          monitorName: data.monitorName,
+          probeName: data.probeName,
+          metricName: phaseMetric.metricName,
+          value: phaseMetric.value,
+          description: phaseMetric.description,
+          unit: "ms",
+          extraAttributes: extraAttributes,
+          metricRows: metricRows,
+          metricNameServiceNameMap: metricNameServiceNameMap,
+        });
+      }
+    }
+
+    if ((data.dataToProcess as ProbeMonitorResponse).pingResponse) {
+      const pingResponse: PingMonitorResponse = (
+        data.dataToProcess as ProbeMonitorResponse
+      ).pingResponse!;
+
+      const extraAttributes: JSONObject = {
+        probeId: (
+          data.dataToProcess as ProbeMonitorResponse
+        ).probeId.toString(),
+      };
+
+      await this.pushMonitorMetric({
+        projectId: data.projectId,
+        monitorId: data.monitorId,
+        monitorName: data.monitorName,
+        probeName: data.probeName,
+        metricName: MonitorMetricType.PacketLossPercent,
+        value: pingResponse.packetLossPercent,
+        description: CheckOn.PacketLossPercent + " for this monitor",
+        unit: "%",
+        extraAttributes: extraAttributes,
+        metricRows: metricRows,
+        metricNameServiceNameMap: metricNameServiceNameMap,
+      });
+
+      await this.pushMonitorMetric({
+        projectId: data.projectId,
+        monitorId: data.monitorId,
+        monitorName: data.monitorName,
+        probeName: data.probeName,
+        metricName: MonitorMetricType.Jitter,
+        value: pingResponse.jitterInMs,
+        description: CheckOn.Jitter + " for this monitor",
+        unit: "ms",
+        extraAttributes: extraAttributes,
+        metricRows: metricRows,
+        metricNameServiceNameMap: metricNameServiceNameMap,
+      });
+    }
+
     if ((data.dataToProcess as ProbeMonitorResponse).isOnline !== undefined) {
       const extraAttributes: JSONObject = {
         probeId: (

package/Tests/Server/Services/AIAgentTaskServiceClaim.test.ts

@@ -0,0 +1,146 @@
+import AIAgentTaskService from "../../../Server/Services/AIAgentTaskService";
+import Model from "../../../Models/DatabaseModels/AIAgentTask";
+import AIAgentTaskStatus from "../../../Types/AI/AIAgentTaskStatus";
+import ObjectID from "../../../Types/ObjectID";
+import { describe, expect, test, afterEach } from "@jest/globals";
+
+/*
+ * claimNextScheduledTask is the atomic-claim fix for the get-pending-task
+ * double-processing race: multiple KEDA-scaled AIAgent workers poll the same
+ * endpoint, and the old plain findOneBy returned the oldest Scheduled task
+ * without mutating it, so two workers could both receive — and both execute —
+ * the same task.
+ *
+ * The claim collapses the read-then-take into findOneBy + a status-guarded
+ * updateOneBy (Scheduled -> InProgress). updateOneBy returns the number of
+ * rows changed: 1 means this caller won the claim; 0 means another worker
+ * already took the task, and the loop retries with the next candidate.
+ *
+ * These tests mock the two inherited persistence helpers (no Postgres) to
+ * lock in:
+ *   (a) a won claim returns the task, with the guard and the InProgress
+ *       transition on the exact row that was read;
+ *   (b) a lost claim (0 rows) is never returned — the loop moves to the
+ *       next candidate;
+ *   (c) no Scheduled tasks => null, with no write at all;
+ *   (d) the retry loop is bounded, so a pathological all-losses storm
+ *       terminates.
+ */
+
+function fakeTask(id: ObjectID): Model {
+  return {
+    id,
+    _id: id.toString(),
+    projectId: ObjectID.generate(),
+    taskType: "FixException",
+  } as unknown as Model;
+}
+
+describe("AIAgentTaskService.claimNextScheduledTask", () => {
+  const aiAgentId: ObjectID = ObjectID.generate();
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  test("returns the task when the claim wins, guarding on Scheduled status", async () => {
+    const task: Model = fakeTask(ObjectID.generate());
+
+    const findOneBy: jest.SpyInstance = jest
+      .spyOn(AIAgentTaskService, "findOneBy")
+      .mockResolvedValue(task);
+    const updateOneBy: jest.SpyInstance = jest
+      .spyOn(AIAgentTaskService, "updateOneBy")
+      .mockResolvedValue(1);
+
+    const claimed: Model | null =
+      await AIAgentTaskService.claimNextScheduledTask({
+        aiAgentId: aiAgentId,
+      });
+
+    expect(claimed).toBe(task);
+    expect(findOneBy).toHaveBeenCalledTimes(1);
+    expect(findOneBy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        query: { status: AIAgentTaskStatus.Scheduled },
+      }),
+    );
+    expect(updateOneBy).toHaveBeenCalledTimes(1);
+    expect(updateOneBy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        query: {
+          _id: task.id!.toString(),
+          status: AIAgentTaskStatus.Scheduled,
+        },
+        data: expect.objectContaining({
+          status: AIAgentTaskStatus.InProgress,
+          aiAgentId: aiAgentId,
+          startedAt: expect.any(Date),
+        }),
+      }),
+    );
+  });
+
+  test("retries with the next candidate when another worker wins the race", async () => {
+    const lostTask: Model = fakeTask(ObjectID.generate());
+    const wonTask: Model = fakeTask(ObjectID.generate());
+
+    const findOneBy: jest.SpyInstance = jest
+      .spyOn(AIAgentTaskService, "findOneBy")
+      .mockResolvedValueOnce(lostTask)
+      .mockResolvedValueOnce(wonTask);
+    const updateOneBy: jest.SpyInstance = jest
+      .spyOn(AIAgentTaskService, "updateOneBy")
+      .mockResolvedValueOnce(0)
+      .mockResolvedValueOnce(1);
+
+    const claimed: Model | null =
+      await AIAgentTaskService.claimNextScheduledTask({
+        aiAgentId: aiAgentId,
+      });
+
+    expect(claimed).toBe(wonTask);
+    expect(findOneBy).toHaveBeenCalledTimes(2);
+    expect(updateOneBy).toHaveBeenCalledTimes(2);
+    expect(updateOneBy).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        query: {
+          _id: wonTask.id!.toString(),
+          status: AIAgentTaskStatus.Scheduled,
+        },
+      }),
+    );
+  });
+
+  test("returns null without writing when no Scheduled task exists", async () => {
+    jest.spyOn(AIAgentTaskService, "findOneBy").mockResolvedValue(null);
+    const updateOneBy: jest.SpyInstance = jest
+      .spyOn(AIAgentTaskService, "updateOneBy")
+      .mockResolvedValue(1);
+
+    const claimed: Model | null =
+      await AIAgentTaskService.claimNextScheduledTask({
+        aiAgentId: aiAgentId,
+      });
+
+    expect(claimed).toBeNull();
+    expect(updateOneBy).not.toHaveBeenCalled();
+  });
+
+  test("gives up after a bounded number of lost claims", async () => {
+    const findOneBy: jest.SpyInstance = jest
+      .spyOn(AIAgentTaskService, "findOneBy")
+      .mockImplementation(async () => {
+        return fakeTask(ObjectID.generate());
+      });
+    jest.spyOn(AIAgentTaskService, "updateOneBy").mockResolvedValue(0);
+
+    const claimed: Model | null =
+      await AIAgentTaskService.claimNextScheduledTask({
+        aiAgentId: aiAgentId,
+      });
+
+    expect(claimed).toBeNull();
+    expect(findOneBy).toHaveBeenCalledTimes(5);
+  });
+});

package/Tests/Server/Services/LogAggregationService.test.ts

@@ -98,6 +98,7 @@ describe("LogAggregationService", () => {
     ).buildHistogramStatement({
       ...defaultRequest,
       facetKey: undefined,
+      bucketSizeInMinutes: 60,
       attributes: { requestid: "uuid-123" },
     });
 
@@ -110,4 +111,25 @@ describe("LogAggregationService", () => {
     expect(Object.values(statement.query_params)).toContain("requestid");
     expect(Object.values(statement.query_params)).toContain("uuid-123");
   });
+
+  test("histogram supports multi-value dashboard attribute filters", () => {
+    const statement: Statement = (
+      LogAggregationService as any
+    ).buildHistogramStatement({
+      ...defaultRequest,
+      facetKey: undefined,
+      bucketSizeInMinutes: 60,
+      attributes: { region: ["eu-west-1", "us-east-1"] },
+    });
+
+    expect(statement.query).toContain(
+      "arrayExists((k, v) -> lowerUTF8(k) = lowerUTF8(",
+    );
+    expect(statement.query).toContain("AND v IN (");
+    expect(Object.values(statement.query_params)).toContain("region");
+    expect(Object.values(statement.query_params)).toContainEqual([
+      "eu-west-1",
+      "us-east-1",
+    ]);
+  });
 });

package/Tests/Server/Services/MetricServiceAggregate.test.ts

@@ -0,0 +1,194 @@
+import "../TestingUtils/Init";
+import { MetricService } from "../../../Server/Services/MetricService";
+import Metric from "../../../Models/AnalyticsModels/Metric";
+import AggregateBy from "../../../Server/Types/AnalyticsDatabase/AggregateBy";
+import { Statement } from "../../../Server/Utils/AnalyticsDatabase/Statement";
+import AggregationType from "../../../Types/BaseDatabase/AggregationType";
+import InBetween from "../../../Types/BaseDatabase/InBetween";
+import SortOrder from "../../../Types/BaseDatabase/SortOrder";
+import BadDataException from "../../../Types/Exception/BadDataException";
+import ObjectID from "../../../Types/ObjectID";
+
+describe("MetricService aggregate statement generation", () => {
+  const projectId: ObjectID = ObjectID.generate();
+  const startDate: Date = new Date("2026-07-09T19:08:00.000Z");
+  const endDate: Date = new Date("2026-07-09T19:13:00.000Z");
+
+  let service: MetricService;
+
+  beforeEach(() => {
+    service = new MetricService();
+  });
+
+  type BuildAggregateByFunction = (
+    overrides?: Partial<AggregateBy<Metric>>,
+  ) => AggregateBy<Metric>;
+
+  const buildAggregateBy: BuildAggregateByFunction = (
+    overrides?: Partial<AggregateBy<Metric>>,
+  ): AggregateBy<Metric> => {
+    return {
+      query: {
+        projectId: projectId,
+        name: "http.client.request.duration",
+        time: new InBetween(startDate, endDate),
+      } as AggregateBy<Metric>["query"],
+      aggregationType: AggregationType.Avg,
+      aggregateColumnName: "value",
+      aggregationTimestampColumnName: "time",
+      startTimestamp: startDate,
+      endTimestamp: endDate,
+      limit: 10000,
+      skip: 0,
+      sort: { time: SortOrder.Ascending } as AggregateBy<Metric>["sort"],
+      props: { isRoot: true },
+      ...overrides,
+    };
+  };
+
+  type GetQueryFunction = (aggregateBy: AggregateBy<Metric>) => string;
+
+  const getQuery: GetQueryFunction = (
+    aggregateBy: AggregateBy<Metric>,
+  ): string => {
+    const result: { statement: Statement; columns: Array<string> } =
+      service.toAggregateStatement(aggregateBy);
+    return result.statement.query;
+  };
+
+  describe("scalar aggregations", () => {
+    it("routes plain Avg (no filters, no group-by, no distribution hint) to the minute MV", () => {
+      const query: string = getQuery(buildAggregateBy());
+      expect(query).toContain("MetricItemAggMV1m");
+    });
+
+    it("skips the MVs and uses count-weighted expressions when the metric is a distribution (histogram) metric", () => {
+      const aggregateBy: AggregateBy<Metric> = buildAggregateBy();
+      (
+        service as unknown as {
+          pointTypeHintByAggregate: WeakMap<AggregateBy<Metric>, string | null>;
+        }
+      ).pointTypeHintByAggregate.set(aggregateBy, "Histogram");
+
+      const query: string = getQuery(aggregateBy);
+
+      expect(query).not.toContain("MetricItemAggMV1m");
+      /*
+       * Avg must be count-weighted (sum of observation totals divided
+       * by sum of observation counts) — NOT avg(value), which for
+       * histogram rows averages per-export-interval sums.
+       */
+      expect(query).toContain("sum(multiIf(isNotNull(count)");
+      expect(query).toContain("toFloat64(count)");
+      expect(query).not.toContain("avg(value)");
+    });
+
+    it("uses count-weighted expressions on the base table when an attribute filter blocks the MVs", () => {
+      const aggregateBy: AggregateBy<Metric> = buildAggregateBy({
+        query: {
+          projectId: projectId,
+          name: "http.client.request.duration",
+          time: new InBetween(startDate, endDate),
+          attributes: { "oneuptime.service.name": "starship-web" },
+        } as unknown as AggregateBy<Metric>["query"],
+      });
+
+      const query: string = getQuery(aggregateBy);
+
+      expect(query).not.toContain("MetricItemAggMV1m");
+      expect(query).toContain("sum(multiIf(isNotNull(count)");
+    });
+
+    it("groups by individual attribute keys, not the whole attributes map", () => {
+      const aggregateBy: AggregateBy<Metric> = buildAggregateBy({
+        groupByAttributeKeys: ["oneuptime.service.name"],
+      });
+
+      const result: { statement: Statement; columns: Array<string> } =
+        service.toAggregateStatement(aggregateBy);
+      const query: string = result.statement.query;
+
+      // Key extraction is parameter-bound and aliased...
+      expect(query).toMatch(/attributes\[\{p\d+:String\}\] AS __attr_grp_0/);
+      // ...regrouped rows re-project the selected keys as a compact map...
+      expect(query).toMatch(
+        /map\(\{p\d+:String\}, __attr_grp_0\) AS attributes/,
+      );
+      // ...grouping happens on the extracted key, never the Map column.
+      expect(query).toContain("GROUP BY time, __attr_grp_0");
+      expect(query).not.toContain("GROUP BY time, attributes");
+
+      // The selected key reaches the query only as a bound parameter.
+      const parameterValues: Array<unknown> = Object.values(
+        result.statement.query_params,
+      );
+      expect(
+        parameterValues.filter((value: unknown) => {
+          return value === "oneuptime.service.name";
+        }),
+      ).toHaveLength(2); // extraction + map key
+
+      expect(result.columns).toContain("attributes");
+    });
+
+    it("drops a legacy whole-map attributes group-by when key-scoped grouping is requested", () => {
+      const aggregateBy: AggregateBy<Metric> = buildAggregateBy({
+        groupBy: { attributes: true } as AggregateBy<Metric>["groupBy"],
+        groupByAttributeKeys: ["oneuptime.service.name"],
+      });
+
+      const query: string = getQuery(aggregateBy);
+
+      expect(query).toContain("GROUP BY time, __attr_grp_0");
+      expect(query).not.toContain("GROUP BY time, attributes");
+    });
+
+    it("rejects more than 10 group-by attribute keys", () => {
+      const aggregateBy: AggregateBy<Metric> = buildAggregateBy({
+        groupByAttributeKeys: Array.from(
+          { length: 11 },
+          (_: unknown, i: number) => {
+            return `key.${i}`;
+          },
+        ),
+      });
+
+      expect(() => {
+        return service.toAggregateStatement(aggregateBy);
+      }).toThrow(BadDataException);
+    });
+  });
+
+  describe("percentile aggregations", () => {
+    it("keeps the histogram bucket fanout and pools by selected attribute keys", () => {
+      const aggregateBy: AggregateBy<Metric> = buildAggregateBy({
+        aggregationType: AggregationType.P90,
+        groupByAttributeKeys: ["oneuptime.service.name"],
+      });
+
+      const result: { statement: Statement; columns: Array<string> } =
+        service.toAggregateStatement(aggregateBy);
+      const query: string = result.statement.query;
+
+      expect(query).toContain("quantileExactWeighted(0.9)");
+      expect(query).toMatch(/attributes\[\{p\d+:String\}\] AS __attr_grp_0/);
+      expect(query).toMatch(
+        /map\(\{p\d+:String\}, __attr_grp_0\) AS attributes/,
+      );
+      expect(query).toContain("GROUP BY time, __attr_grp_0");
+      expect(result.columns).toContain("attributes");
+    });
+
+    it("does not group when no attribute keys are selected (regression: whole-map fragmentation)", () => {
+      const aggregateBy: AggregateBy<Metric> = buildAggregateBy({
+        aggregationType: AggregationType.P90,
+      });
+
+      const query: string = getQuery(aggregateBy);
+
+      expect(query).toContain("quantileExactWeighted(0.9)");
+      expect(query).not.toContain("__attr_grp_0");
+      expect(query).toContain("GROUP BY time");
+    });
+  });
+});

package/Tests/Types/AI/AIAgentTaskStatus.test.ts

@@ -0,0 +1,86 @@
+import AIAgentTaskStatus, {
+  AIAgentTaskStatusHelper,
+  AIAgentTaskStatusProps,
+} from "../../../Types/AI/AIAgentTaskStatus";
+
+describe("AIAgentTaskStatusHelper", () => {
+  describe("getAllStatusProps", () => {
+    test("returns one entry per status with a title and description", () => {
+      const props: Array<AIAgentTaskStatusProps> =
+        AIAgentTaskStatusHelper.getAllStatusProps();
+
+      const statuses: Array<AIAgentTaskStatus> =
+        Object.values(AIAgentTaskStatus);
+      expect(props.length).toBe(statuses.length);
+
+      for (const prop of props) {
+        expect(typeof prop.title).toBe("string");
+        expect(prop.title.length).toBeGreaterThan(0);
+        expect(typeof prop.description).toBe("string");
+        expect(prop.description.length).toBeGreaterThan(0);
+      }
+    });
+
+    test("covers every status in the enum exactly once", () => {
+      const seen: Set<AIAgentTaskStatus> = new Set<AIAgentTaskStatus>();
+      for (const prop of AIAgentTaskStatusHelper.getAllStatusProps()) {
+        expect(seen.has(prop.status)).toBe(false);
+        seen.add(prop.status);
+      }
+
+      for (const status of Object.values(AIAgentTaskStatus)) {
+        expect(seen.has(status)).toBe(true);
+      }
+    });
+  });
+
+  describe("getTitle", () => {
+    test("returns the configured title for a known status", () => {
+      expect(
+        AIAgentTaskStatusHelper.getTitle(AIAgentTaskStatus.InProgress),
+      ).toBe("In Progress");
+      expect(
+        AIAgentTaskStatusHelper.getTitle(AIAgentTaskStatus.Completed),
+      ).toBe("Completed");
+    });
+
+    test("returns an empty string for an unknown status", () => {
+      expect(
+        AIAgentTaskStatusHelper.getTitle("NonExistent" as AIAgentTaskStatus),
+      ).toBe("");
+    });
+  });
+
+  describe("getDescription", () => {
+    test("returns a non-empty description for a known status", () => {
+      expect(
+        AIAgentTaskStatusHelper.getDescription(AIAgentTaskStatus.Scheduled)
+          .length,
+      ).toBeGreaterThan(0);
+    });
+
+    test("returns an empty string for an unknown status", () => {
+      expect(
+        AIAgentTaskStatusHelper.getDescription(
+          "NonExistent" as AIAgentTaskStatus,
+        ),
+      ).toBe("");
+    });
+  });
+
+  describe("isTerminalStatus", () => {
+    test.each([AIAgentTaskStatus.Completed, AIAgentTaskStatus.Error])(
+      "returns true for terminal status %s",
+      (status: AIAgentTaskStatus) => {
+        expect(AIAgentTaskStatusHelper.isTerminalStatus(status)).toBe(true);
+      },
+    );
+
+    test.each([AIAgentTaskStatus.Scheduled, AIAgentTaskStatus.InProgress])(
+      "returns false for non-terminal status %s",
+      (status: AIAgentTaskStatus) => {
+        expect(AIAgentTaskStatusHelper.isTerminalStatus(status)).toBe(false);
+      },
+    );
+  });
+});