From a98f292a11e301609cfd49e5e2e90198c2fd103e Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 4 Jun 2026 16:26:49 -0400 Subject: [PATCH] docs: document status tool tests --- src/agents/tools/assistant-phase-text.test.ts | 4 ++++ src/agents/tools/sessions-list-tool.test.ts | 6 ++++++ src/agents/tools/sessions-yield-tool.test.ts | 4 ++++ src/agents/tools/update-plan-tool.test.ts | 3 +++ src/agents/tools/web-shared.test.ts | 4 ++++ 5 files changed, 21 insertions(+) diff --git a/src/agents/tools/assistant-phase-text.test.ts b/src/agents/tools/assistant-phase-text.test.ts index 8bc3aca980e9..921045f1b231 100644 --- a/src/agents/tools/assistant-phase-text.test.ts +++ b/src/agents/tools/assistant-phase-text.test.ts @@ -1,3 +1,5 @@ +// Assistant phase text tests cover extracting final-answer text from signed +// assistant message phases. import { describe, expect, it } from "vitest"; import { extractAssistantText as extractChatHistoryAssistantText } from "./chat-history-text.js"; import { extractAssistantText as extractSessionAssistantText } from "./session-message-text.js"; @@ -52,6 +54,8 @@ describe("phase-aware assistant text helpers", () => { } it("does not fall back to commentary when an explicit final_answer is empty", () => { + // An explicit empty final answer means there is no publishable response; + // commentary should stay private. const message = assistantMessage( assistantTextPart("commentary", "commentary", "Need simpler use cat overwrite full file."), assistantTextPart("final", "final_answer", " "), diff --git a/src/agents/tools/sessions-list-tool.test.ts b/src/agents/tools/sessions-list-tool.test.ts index 0560944772db..371eba6c36f3 100644 --- a/src/agents/tools/sessions-list-tool.test.ts +++ b/src/agents/tools/sessions-list-tool.test.ts @@ -1,3 +1,5 @@ +// sessions_list tool tests cover session metadata projection, visibility +// helpers, and numeric argument validation. import { beforeEach, describe, expect, it, vi } from "vitest"; import { createSessionsListTool } from "./sessions-list-tool.js"; @@ -69,6 +71,8 @@ describe("sessions-list-tool", () => { }); it("keeps deliveryContext.threadId in sessions_list results", async () => { + // Thread/topic ids are required for channel-specific follow-up routing, so + // list results must preserve both string and numeric variants. mocks.gatewayCall.mockImplementation(async (opts: unknown) => { const request = opts as { method?: string }; if (request.method === "sessions.list") { @@ -200,6 +204,8 @@ describe("sessions-list-tool", () => { [{ messageLimit: 1.5 }, "messageLimit must be a non-negative integer"], [{ messageLimit: -1 }, "messageLimit must be a non-negative integer"], ])("rejects invalid numeric parameter %o", async (params, message) => { + // Reject before gateway dispatch so malformed limits cannot reach session + // store queries. const tool = createSessionsListTool({ config: {} as never }); await expect(tool.execute("call-4", params)).rejects.toThrow(message); diff --git a/src/agents/tools/sessions-yield-tool.test.ts b/src/agents/tools/sessions-yield-tool.test.ts index 7b6a1ecb2b22..b6dab8f7b073 100644 --- a/src/agents/tools/sessions-yield-tool.test.ts +++ b/src/agents/tools/sessions-yield-tool.test.ts @@ -1,3 +1,5 @@ +// sessions_yield tool tests cover cooperative turn yielding and unsupported +// context errors. import { describe, expect, it, vi } from "vitest"; import { createSessionsYieldTool } from "./sessions-yield-tool.js"; @@ -30,6 +32,8 @@ describe("sessions_yield tool", () => { }); it("passes the custom message through the yield callback", async () => { + // The callback message becomes operator-visible scheduler context, so the + // tool must not replace a supplied reason with the default text. const onYield = vi.fn(); const tool = createSessionsYieldTool({ sessionId: "test-session", onYield }); const result = await tool.execute("call-1", { message: "Waiting for fact-checker" }); diff --git a/src/agents/tools/update-plan-tool.test.ts b/src/agents/tools/update-plan-tool.test.ts index 59cc01a24f3e..04d304f15f3e 100644 --- a/src/agents/tools/update-plan-tool.test.ts +++ b/src/agents/tools/update-plan-tool.test.ts @@ -1,3 +1,4 @@ +// update_plan tool tests cover compact plan payloads and plan-shape validation. import { describe, expect, it } from "vitest"; import { createUpdatePlanTool } from "./update-plan-tool.js"; @@ -26,6 +27,8 @@ describe("update_plan tool", () => { }); it("rejects multiple in-progress steps", async () => { + // The UI and agent state assume one current step; multiple active steps + // make progress reporting ambiguous. const tool = createUpdatePlanTool(); await expect( diff --git a/src/agents/tools/web-shared.test.ts b/src/agents/tools/web-shared.test.ts index 20adcadc53cd..b1c6496efa99 100644 --- a/src/agents/tools/web-shared.test.ts +++ b/src/agents/tools/web-shared.test.ts @@ -1,3 +1,5 @@ +// Shared web helper tests cover timeout normalization and process-local cache +// expiry guards. import { MAX_TIMER_TIMEOUT_MS, MAX_TIMER_TIMEOUT_SECONDS, @@ -32,6 +34,8 @@ describe("web shared timeout seconds", () => { }); it("drops cached values while the process clock is invalid", () => { + // Bad system clocks can make cache expiry nonsensical; fail closed instead + // of serving stale web data indefinitely. const cache = new Map>(); writeCache(cache, "key", "old", 60_000); expect(readCache(cache, "key")?.value).toBe("old");