@oneuptime/common 12.0.8 → 12.0.9

package/Tests/Server/Utils/AI/StatusPageTools.test.ts

@@ -0,0 +1,391 @@
+import {
+  QueryStatusPageAnnouncementsTool,
+  QueryStatusPagesTool,
+} from "../../../../Server/Utils/AI/Toolbox/StatusPageTools";
+import {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../Server/Utils/AI/Toolbox/ToolTypes";
+import StatusPageService from "../../../../Server/Services/StatusPageService";
+import StatusPageAnnouncementService from "../../../../Server/Services/StatusPageAnnouncementService";
+import StatusPageResourceService from "../../../../Server/Services/StatusPageResourceService";
+import StatusPageSubscriberService from "../../../../Server/Services/StatusPageSubscriberService";
+import StatusPage from "../../../../Models/DatabaseModels/StatusPage";
+import StatusPageAnnouncement from "../../../../Models/DatabaseModels/StatusPageAnnouncement";
+import StatusPageResource from "../../../../Models/DatabaseModels/StatusPageResource";
+import Monitor from "../../../../Models/DatabaseModels/Monitor";
+import { AIChatCitationTargetType } from "../../../../Types/AI/AIChatTypes";
+import { JSONObject } from "../../../../Types/JSON";
+import ObjectID from "../../../../Types/ObjectID";
+import PositiveNumber from "../../../../Types/PositiveNumber";
+import { afterEach, describe, expect, test } from "@jest/globals";
+
+/*
+ * query_status_pages / query_status_page_announcements close the gap where
+ * chat could post public status updates but could not see which status pages
+ * exist or what they already say. These tests lock in what the model relies
+ * on: list mode shows every page (with visibility and public URL) and pages
+ * honestly, detail mode shows the public blast radius (resources shown) and
+ * the reach of a post (active subscriber count), and citations deep-link to
+ * the right dashboard page.
+ */
+
+const ctx: ToolContext = {
+  projectId: ObjectID.generate(),
+  props: { isRoot: true },
+};
+
+const PAGE_ID: ObjectID = ObjectID.generate();
+
+function buildStatusPage(data?: {
+  id?: ObjectID;
+  name?: string;
+  isPublic?: boolean;
+}): StatusPage {
+  const statusPage: StatusPage = new StatusPage();
+  statusPage._id = (data?.id ?? PAGE_ID).toString();
+  statusPage.name = data?.name ?? "Acme Status";
+  statusPage.description = "Customer-facing status page.";
+  statusPage.isPublicStatusPage = data?.isPublic ?? true;
+  return statusPage;
+}
+
+function buildResource(
+  displayName: string,
+  monitorName?: string,
+): StatusPageResource {
+  const resource: StatusPageResource = new StatusPageResource();
+  resource._id = ObjectID.generate().toString();
+  resource.displayName = displayName;
+
+  if (monitorName) {
+    const monitor: Monitor = new Monitor();
+    monitor.name = monitorName;
+    resource.monitor = monitor;
+  }
+
+  return resource;
+}
+
+function buildAnnouncement(data?: {
+  title?: string;
+  pages?: Array<string>;
+}): StatusPageAnnouncement {
+  const announcement: StatusPageAnnouncement = new StatusPageAnnouncement();
+  announcement._id = ObjectID.generate().toString();
+  announcement.title = data?.title ?? "Elevated error rates";
+  announcement.description = "We are investigating elevated error rates.";
+  announcement.showAnnouncementAt = new Date("2026-08-01T10:00:00Z");
+
+  announcement.statusPages = (data?.pages ?? ["Acme Status"]).map(
+    (name: string): StatusPage => {
+      const statusPage: StatusPage = new StatusPage();
+      statusPage.name = name;
+      return statusPage;
+    },
+  );
+
+  return announcement;
+}
+
+afterEach(() => {
+  jest.restoreAllMocks();
+});
+
+describe("query_status_pages — list mode", () => {
+  test("lists status pages with visibility and public URL, with a list citation", async () => {
+    const findBySpy: jest.SpyInstance = jest
+      .spyOn(StatusPageService, "findBy")
+      .mockResolvedValue([
+        buildStatusPage(),
+        buildStatusPage({
+          id: ObjectID.generate(),
+          name: "Internal Status",
+          isPublic: false,
+        }),
+      ] as never);
+    jest
+      .spyOn(StatusPageService, "countBy")
+      .mockResolvedValue(new PositiveNumber(2) as never);
+    jest
+      .spyOn(StatusPageService, "getStatusPageURL")
+      .mockResolvedValue("https://status.acme.dev" as never);
+
+    const result: ToolExecutionResult = await QueryStatusPagesTool.execute(
+      {},
+      ctx,
+    );
+
+    expect(result.rowCount).toBe(2);
+    expect(result.dataForLlm).toContain("Acme Status");
+    expect(result.dataForLlm).toContain("Internal Status");
+    expect(result.dataForLlm).toContain("https://status.acme.dev");
+    expect(result.dataForLlm).toContain("Private");
+    // All rows returned: no paging banner.
+    expect(result.dataForLlm).not.toContain("Showing rows");
+    expect(result.citationLabel).toBe("Status pages (2 total)");
+    expect(result.citationTarget).toEqual({
+      type: AIChatCitationTargetType.StatusPages,
+    });
+    expect(result.widget).toBeDefined();
+
+    // The query must run under the requesting user's props, never as root+.
+    const callArgs: JSONObject = findBySpy.mock.calls[0]?.[0] as JSONObject;
+    expect(callArgs["props"]).toBe(ctx.props);
+    expect(callArgs["limit"]).toBe(10);
+    expect(callArgs["skip"]).toBe(0);
+  });
+
+  test("marks a paged slice honestly and puts the total in the citation", async () => {
+    jest
+      .spyOn(StatusPageService, "findBy")
+      .mockResolvedValue([
+        buildStatusPage(),
+        buildStatusPage({ id: ObjectID.generate(), name: "EU Status" }),
+      ] as never);
+    jest
+      .spyOn(StatusPageService, "countBy")
+      .mockResolvedValue(new PositiveNumber(5) as never);
+    jest
+      .spyOn(StatusPageService, "getStatusPageURL")
+      .mockResolvedValue("https://status.acme.dev" as never);
+
+    const result: ToolExecutionResult = await QueryStatusPagesTool.execute(
+      {},
+      ctx,
+    );
+
+    expect(result.dataForLlm.startsWith("Showing rows 1–2 of 5 total.")).toBe(
+      true,
+    );
+    expect(result.citationLabel).toBe("Status pages (5 total)");
+  });
+
+  test("clamps limit and skip; an empty project is honest", async () => {
+    const findBySpy: jest.SpyInstance = jest
+      .spyOn(StatusPageService, "findBy")
+      .mockResolvedValue([] as never);
+    jest
+      .spyOn(StatusPageService, "countBy")
+      .mockResolvedValue(new PositiveNumber(0) as never);
+
+    const result: ToolExecutionResult = await QueryStatusPagesTool.execute(
+      { limit: 999, skip: 99999 },
+      ctx,
+    );
+
+    expect(result.rowCount).toBe(0);
+    expect(result.widget).toBeUndefined();
+
+    const callArgs: JSONObject = findBySpy.mock.calls[0]?.[0] as JSONObject;
+    expect(callArgs["limit"]).toBe(25);
+    expect(callArgs["skip"]).toBe(500);
+  });
+
+  test("a public URL lookup failure degrades to no URL, not a tool error", async () => {
+    jest
+      .spyOn(StatusPageService, "findBy")
+      .mockResolvedValue([buildStatusPage()] as never);
+    jest
+      .spyOn(StatusPageService, "countBy")
+      .mockResolvedValue(new PositiveNumber(1) as never);
+    jest
+      .spyOn(StatusPageService, "getStatusPageURL")
+      .mockRejectedValue(new Error("global config unavailable") as never);
+
+    const result: ToolExecutionResult = await QueryStatusPagesTool.execute(
+      {},
+      ctx,
+    );
+
+    expect(result.rowCount).toBe(1);
+    expect(result.dataForLlm).toContain("Acme Status");
+    expect(result.dataForLlm).not.toContain("publicUrl=");
+  });
+});
+
+describe("query_status_pages — detail mode", () => {
+  test("returns the page's public resources and active subscriber count with a view citation", async () => {
+    jest
+      .spyOn(StatusPageService, "findOneById")
+      .mockResolvedValue(buildStatusPage() as never);
+    jest
+      .spyOn(StatusPageResourceService, "findBy")
+      .mockResolvedValue([
+        buildResource("Checkout", "checkout-api"),
+        buildResource("CDN"),
+      ] as never);
+    const countBySpy: jest.SpyInstance = jest
+      .spyOn(StatusPageSubscriberService, "countBy")
+      .mockResolvedValue(new PositiveNumber(42) as never);
+    jest
+      .spyOn(StatusPageService, "getStatusPageURL")
+      .mockResolvedValue("https://status.acme.dev" as never);
+
+    const result: ToolExecutionResult = await QueryStatusPagesTool.execute(
+      { statusPageId: PAGE_ID.toString() },
+      ctx,
+    );
+
+    expect(result.rowCount).toBe(1);
+    expect(result.dataForLlm).toContain("Checkout (monitor: checkout-api)");
+    expect(result.dataForLlm).toContain("CDN");
+    expect(result.dataForLlm).toContain("activeSubscriberCount=42");
+    expect(result.dataForLlm).toContain("https://status.acme.dev");
+    expect(result.citationLabel).toBe('Status page "Acme Status"');
+    expect(result.citationTarget).toEqual({
+      type: AIChatCitationTargetType.StatusPageView,
+      params: { statusPageId: PAGE_ID.toString() },
+    });
+    expect(result.widget).toBeDefined();
+
+    /*
+     * The subscriber count must be the real reach of a post: scoped to this
+     * page and to confirmed, still-subscribed recipients — under the
+     * requesting user's props, pinned to the tenant (statusPageId is an
+     * untrusted model argument).
+     */
+    const countArgs: JSONObject = countBySpy.mock.calls[0]?.[0] as JSONObject;
+    const countQuery: JSONObject = countArgs["query"] as JSONObject;
+    expect(countQuery["statusPageId"]?.toString()).toBe(PAGE_ID.toString());
+    expect(countQuery["projectId"]).toBe(ctx.projectId);
+    expect(countQuery["isUnsubscribed"]).toBe(false);
+    expect(countQuery["isSubscriptionConfirmed"]).toBe(true);
+    expect(countArgs["props"]).toBe(ctx.props);
+  });
+
+  test("a missing page is honest: zero rows, no widget, no follow-up queries", async () => {
+    jest
+      .spyOn(StatusPageService, "findOneById")
+      .mockResolvedValue(null as never);
+    const resourcesSpy: jest.SpyInstance = jest
+      .spyOn(StatusPageResourceService, "findBy")
+      .mockResolvedValue([] as never);
+    const subscribersSpy: jest.SpyInstance = jest
+      .spyOn(StatusPageSubscriberService, "countBy")
+      .mockResolvedValue(new PositiveNumber(0) as never);
+
+    const result: ToolExecutionResult = await QueryStatusPagesTool.execute(
+      { statusPageId: PAGE_ID.toString() },
+      ctx,
+    );
+
+    expect(result.rowCount).toBe(0);
+    expect(result.widget).toBeUndefined();
+    expect(resourcesSpy).not.toHaveBeenCalled();
+    expect(subscribersSpy).not.toHaveBeenCalled();
+  });
+});
+
+describe("query_status_page_announcements", () => {
+  test("lists recent announcements with the pages they appear on", async () => {
+    const findBySpy: jest.SpyInstance = jest
+      .spyOn(StatusPageAnnouncementService, "findBy")
+      .mockResolvedValue([
+        buildAnnouncement(),
+        buildAnnouncement({
+          title: "Maintenance window scheduled",
+          pages: ["Acme Status", "EU Status"],
+        }),
+      ] as never);
+    jest
+      .spyOn(StatusPageAnnouncementService, "countBy")
+      .mockResolvedValue(new PositiveNumber(2) as never);
+
+    const result: ToolExecutionResult =
+      await QueryStatusPageAnnouncementsTool.execute({}, ctx);
+
+    expect(result.rowCount).toBe(2);
+    expect(result.dataForLlm).toContain("Elevated error rates");
+    expect(result.dataForLlm).toContain("Maintenance window scheduled");
+    expect(result.dataForLlm).toContain("Acme Status, EU Status");
+    expect(result.dataForLlm).toContain("2026-08-01");
+    expect(result.citationLabel).toBe(
+      "Status page announcements, last 30d (2 total)",
+    );
+    expect(result.citationTarget).toEqual({
+      type: AIChatCitationTargetType.StatusPages,
+    });
+    expect(result.widget).toBeDefined();
+
+    // Unfiltered call: window filter present, no relation filter, user props.
+    const callArgs: JSONObject = findBySpy.mock.calls[0]?.[0] as JSONObject;
+    const query: JSONObject = callArgs["query"] as JSONObject;
+    expect(query["showAnnouncementAt"]).toBeDefined();
+    expect(query["statusPages"]).toBeUndefined();
+    expect(callArgs["props"]).toBe(ctx.props);
+    expect(callArgs["limit"]).toBe(10);
+  });
+
+  test("statusPageId filter reaches the relation query and switches the citation", async () => {
+    const findBySpy: jest.SpyInstance = jest
+      .spyOn(StatusPageAnnouncementService, "findBy")
+      .mockResolvedValue([buildAnnouncement()] as never);
+    jest
+      .spyOn(StatusPageAnnouncementService, "countBy")
+      .mockResolvedValue(new PositiveNumber(1) as never);
+
+    const result: ToolExecutionResult =
+      await QueryStatusPageAnnouncementsTool.execute(
+        { statusPageId: PAGE_ID.toString() },
+        ctx,
+      );
+
+    const callArgs: JSONObject = findBySpy.mock.calls[0]?.[0] as JSONObject;
+    const query: JSONObject = callArgs["query"] as JSONObject;
+    expect(query["statusPages"]?.toString()).toBe(PAGE_ID.toString());
+    // The untrusted id filter must come pinned to the tenant from ctx.
+    expect(query["projectId"]).toBe(ctx.projectId);
+
+    expect(result.citationTarget).toEqual({
+      type: AIChatCitationTargetType.StatusPageView,
+      params: { statusPageId: PAGE_ID.toString() },
+    });
+  });
+
+  test("clamps withinDays and limit", async () => {
+    const findBySpy: jest.SpyInstance = jest
+      .spyOn(StatusPageAnnouncementService, "findBy")
+      .mockResolvedValue([] as never);
+    jest
+      .spyOn(StatusPageAnnouncementService, "countBy")
+      .mockResolvedValue(new PositiveNumber(0) as never);
+
+    const result: ToolExecutionResult =
+      await QueryStatusPageAnnouncementsTool.execute(
+        { withinDays: 99999, limit: 500 },
+        ctx,
+      );
+
+    expect(result.citationLabel).toBe(
+      "Status page announcements, last 365d (0 total)",
+    );
+
+    const callArgs: JSONObject = findBySpy.mock.calls[0]?.[0] as JSONObject;
+    expect(callArgs["limit"]).toBe(25);
+  });
+
+  test("an empty window is honest: zero rows and no widget", async () => {
+    jest
+      .spyOn(StatusPageAnnouncementService, "findBy")
+      .mockResolvedValue([] as never);
+    jest
+      .spyOn(StatusPageAnnouncementService, "countBy")
+      .mockResolvedValue(new PositiveNumber(0) as never);
+
+    const result: ToolExecutionResult =
+      await QueryStatusPageAnnouncementsTool.execute({}, ctx);
+
+    expect(result.rowCount).toBe(0);
+    expect(result.widget).toBeUndefined();
+  });
+});
+
+describe("status page tools — permissions", () => {
+  test("required permissions derive from the model read ACLs", () => {
+    expect(QueryStatusPagesTool.requiredPermissions.length).toBeGreaterThan(0);
+    expect(
+      QueryStatusPageAnnouncementsTool.requiredPermissions.length,
+    ).toBeGreaterThan(0);
+  });
+});

package/Tests/Server/Utils/AI/TeamTools.test.ts

@@ -0,0 +1,257 @@
+import { QueryTeamsTool } from "../../../../Server/Utils/AI/Toolbox/TeamTools";
+import {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../Server/Utils/AI/Toolbox/ToolTypes";
+import TeamService from "../../../../Server/Services/TeamService";
+import TeamMemberService from "../../../../Server/Services/TeamMemberService";
+import Team from "../../../../Models/DatabaseModels/Team";
+import TeamMember from "../../../../Models/DatabaseModels/TeamMember";
+import User from "../../../../Models/DatabaseModels/User";
+import { AIChatCitationTargetType } from "../../../../Types/AI/AIChatTypes";
+import { JSONObject } from "../../../../Types/JSON";
+import Email from "../../../../Types/Email";
+import Name from "../../../../Types/Name";
+import ObjectID from "../../../../Types/ObjectID";
+import PositiveNumber from "../../../../Types/PositiveNumber";
+import { afterEach, describe, expect, test } from "@jest/globals";
+
+/*
+ * query_teams answers "who is on the platform team?" / "which team should own
+ * this?". These tests lock in what the model relies on: the detail mode
+ * surfaces member NAMES (emails are redacted by the serializer, so a name is
+ * the only member identifier the model can read back), list mode carries a
+ * member count per team, tenancy is pinned from ctx (never an argument), and
+ * empty results are honest (rowCount 0, no widget).
+ */
+
+const ctx: ToolContext = {
+  projectId: ObjectID.generate(),
+  props: { isRoot: true },
+};
+
+const TEAM_ID: ObjectID = ObjectID.generate();
+
+function buildTeam(data?: {
+  id?: ObjectID;
+  name?: string;
+  description?: string;
+}): Team {
+  const team: Team = new Team();
+  team._id = (data?.id ?? TEAM_ID).toString();
+  team.name = data?.name ?? "Platform";
+  team.description = data?.description ?? "Owns shared infrastructure.";
+  return team;
+}
+
+function buildMember(data: {
+  name: string;
+  email: string;
+  teamId?: ObjectID;
+  hasAcceptedInvitation?: boolean;
+}): TeamMember {
+  const member: TeamMember = new TeamMember();
+  member._id = ObjectID.generate().toString();
+  if (data.teamId) {
+    member.teamId = data.teamId;
+  }
+  member.hasAcceptedInvitation = data.hasAcceptedInvitation ?? true;
+
+  const user: User = new User();
+  user._id = ObjectID.generate().toString();
+  user.name = new Name(data.name);
+  user.email = new Email(data.email);
+  member.user = user;
+
+  return member;
+}
+
+afterEach(() => {
+  jest.restoreAllMocks();
+});
+
+describe("query_teams — detail mode", () => {
+  test("returns the team's members by name, with emails redacted for the LLM", async () => {
+    jest
+      .spyOn(TeamService, "findOneById")
+      .mockResolvedValue(buildTeam() as never);
+
+    const membersSpy: jest.SpyInstance = jest
+      .spyOn(TeamMemberService, "findBy")
+      .mockResolvedValue([
+        buildMember({ name: "Sam Iyer", email: "sam@acme.com" }),
+        buildMember({
+          name: "Riya Patel",
+          email: "riya@acme.com",
+          hasAcceptedInvitation: false,
+        }),
+      ] as never);
+
+    const result: ToolExecutionResult = await QueryTeamsTool.execute(
+      { teamId: TEAM_ID.toString() },
+      ctx,
+    );
+
+    // One team header row + two member rows.
+    expect(result.rowCount).toBe(3);
+    expect(result.dataForLlm).toContain("Platform");
+    expect(result.dataForLlm).toContain("Sam Iyer");
+    expect(result.dataForLlm).toContain("Riya Patel");
+    expect(result.dataForLlm).toContain("invited (not yet accepted)");
+
+    // The serializer must strip emails — names are the usable identifier.
+    expect(result.dataForLlm).not.toContain("sam@acme.com");
+    expect(result.dataForLlm).toContain("[redacted-email]");
+    expect(result.redactionCount).toBeGreaterThanOrEqual(2);
+
+    expect(result.citationLabel).toBe('Team "Platform" (2 members)');
+    expect(result.citationTarget).toEqual({
+      type: AIChatCitationTargetType.Teams,
+    });
+    expect(result.widget).toBeDefined();
+
+    /*
+     * teamId is an untrusted model argument, so the member fetch must be
+     * pinned to the tenant from ctx and run under the user's own props.
+     */
+    const callArgs: JSONObject = membersSpy.mock.calls[0]?.[0] as JSONObject;
+    const query: JSONObject = callArgs["query"] as JSONObject;
+    expect(String(query["teamId"])).toBe(TEAM_ID.toString());
+    expect(query["projectId"]).toBe(ctx.projectId);
+    expect(callArgs["props"]).toBe(ctx.props);
+  });
+
+  test("a missing team is honest: zero rows, no widget", async () => {
+    jest.spyOn(TeamService, "findOneById").mockResolvedValue(null as never);
+    const membersSpy: jest.SpyInstance = jest
+      .spyOn(TeamMemberService, "findBy")
+      .mockResolvedValue([] as never);
+
+    const result: ToolExecutionResult = await QueryTeamsTool.execute(
+      { teamId: TEAM_ID.toString() },
+      ctx,
+    );
+
+    expect(result.rowCount).toBe(0);
+    expect(result.widget).toBeUndefined();
+    // No team, no member fetch.
+    expect(membersSpy).not.toHaveBeenCalled();
+  });
+});
+
+describe("query_teams — list mode", () => {
+  test("lists teams with a member count per team", async () => {
+    const otherTeamId: ObjectID = ObjectID.generate();
+
+    const teamsSpy: jest.SpyInstance = jest
+      .spyOn(TeamService, "findBy")
+      .mockResolvedValue([
+        buildTeam({ id: TEAM_ID, name: "Platform" }),
+        buildTeam({
+          id: otherTeamId,
+          name: "SRE",
+          description: "Runs on-call.",
+        }),
+      ] as never);
+    jest
+      .spyOn(TeamService, "countBy")
+      .mockResolvedValue(new PositiveNumber(2) as never);
+
+    const membersSpy: jest.SpyInstance = jest
+      .spyOn(TeamMemberService, "findBy")
+      .mockResolvedValue([
+        buildMember({ name: "A", email: "a@x.com", teamId: TEAM_ID }),
+        buildMember({ name: "B", email: "b@x.com", teamId: TEAM_ID }),
+        buildMember({ name: "C", email: "c@x.com", teamId: TEAM_ID }),
+        buildMember({ name: "D", email: "d@x.com", teamId: otherTeamId }),
+      ] as never);
+
+    const result: ToolExecutionResult = await QueryTeamsTool.execute({}, ctx);
+
+    expect(result.rowCount).toBe(2);
+    expect(result.dataForLlm).toContain("Platform");
+    expect(result.dataForLlm).toContain("SRE");
+    expect(result.dataForLlm).toContain("memberCount=3");
+    expect(result.dataForLlm).toContain("memberCount=1");
+    expect(result.citationLabel).toBe("Teams (2 found)");
+    expect(result.citationTarget).toEqual({
+      type: AIChatCitationTargetType.Teams,
+    });
+    expect(result.widget).toBeDefined();
+
+    // The team query must run under the requesting user's props, never root+.
+    const teamCallArgs: JSONObject = teamsSpy.mock.calls[0]?.[0] as JSONObject;
+    expect(teamCallArgs["props"]).toBe(ctx.props);
+    expect(teamCallArgs["limit"]).toBe(10);
+
+    // The member-count join fetch is pinned to the tenant from ctx.
+    const memberCallArgs: JSONObject = membersSpy.mock
+      .calls[0]?.[0] as JSONObject;
+    const memberQuery: JSONObject = memberCallArgs["query"] as JSONObject;
+    expect(memberQuery["projectId"]).toBe(ctx.projectId);
+    expect(memberCallArgs["props"]).toBe(ctx.props);
+  });
+
+  test("clamps the limit argument", async () => {
+    const teamsSpy: jest.SpyInstance = jest
+      .spyOn(TeamService, "findBy")
+      .mockResolvedValue([] as never);
+    jest
+      .spyOn(TeamService, "countBy")
+      .mockResolvedValue(new PositiveNumber(0) as never);
+
+    const result: ToolExecutionResult = await QueryTeamsTool.execute(
+      { limit: 999, skip: -5 },
+      ctx,
+    );
+
+    expect(result.citationLabel).toBe("Teams (0 found)");
+
+    const callArgs: JSONObject = teamsSpy.mock.calls[0]?.[0] as JSONObject;
+    expect(callArgs["limit"]).toBe(25);
+    expect(callArgs["skip"]).toBe(0);
+  });
+
+  test("tells the model when it is looking at one page of a longer list", async () => {
+    jest
+      .spyOn(TeamService, "findBy")
+      .mockResolvedValue([
+        buildTeam({ id: TEAM_ID, name: "Platform" }),
+        buildTeam({ id: ObjectID.generate(), name: "SRE" }),
+      ] as never);
+    jest
+      .spyOn(TeamService, "countBy")
+      .mockResolvedValue(new PositiveNumber(7) as never);
+    jest.spyOn(TeamMemberService, "findBy").mockResolvedValue([] as never);
+
+    const result: ToolExecutionResult = await QueryTeamsTool.execute({}, ctx);
+
+    expect(result.dataForLlm).toContain(
+      "Showing rows 1–2 of 7 total. Pass skip to page further.",
+    );
+    expect(result.citationLabel).toBe("Teams (2 of 7)");
+  });
+
+  test("an empty project is honest: zero rows and no widget", async () => {
+    jest.spyOn(TeamService, "findBy").mockResolvedValue([] as never);
+    jest
+      .spyOn(TeamService, "countBy")
+      .mockResolvedValue(new PositiveNumber(0) as never);
+    const membersSpy: jest.SpyInstance = jest
+      .spyOn(TeamMemberService, "findBy")
+      .mockResolvedValue([] as never);
+
+    const result: ToolExecutionResult = await QueryTeamsTool.execute({}, ctx);
+
+    expect(result.rowCount).toBe(0);
+    expect(result.widget).toBeUndefined();
+    // No teams on this page — no member-count fetch either.
+    expect(membersSpy).not.toHaveBeenCalled();
+  });
+});
+
+describe("query_teams — permissions", () => {
+  test("required permissions derive from the model read ACL", () => {
+    expect(QueryTeamsTool.requiredPermissions.length).toBeGreaterThan(0);
+  });
+});