/** * v1.20.0 (F1) — Coach retrieval tool executor: dispatch, grounding, and the * gate-preservation contract. The executor must NEVER throw and must return a * structured `{ present: false }` for an absent domain — the hallucination * audit asserts the model can always tell "no data" from "data". */ import { DEFAULT_UNIT_PREFERENCES } from "@/lib/measurements/display-transform"; import { describe, expect, it, vi, beforeEach } from "vitest"; import type { CoachSnapshotResult } from "@/lib/ai/coach/snapshot"; const buildCoachSnapshot = vi.fn<(userId: string, scope?: unknown) => Promise>(); vi.mock("@/lib/ai/coach/snapshot", () => ({ buildCoachSnapshot: (userId: string, scope?: unknown) => buildCoachSnapshot(userId, scope), })); // v1.33.0 (#648) — an empty window read is no longer reported as absence until // the availability probe has confirmed the record is empty. Stub the probe's // reads to "nothing stored", which is what these dispatch assertions mean by an // absent section; `coach-availability-window-honesty.test.ts` owns the other // three states. vi.mock("@/lib/db", () => ({ prisma: { measurement: { groupBy: () => Promise.resolve([]) }, workout: { aggregate: () => Promise.resolve(emptyAggregate()) }, moodEntry: { aggregate: () => Promise.resolve(emptyAggregate()) }, medicationIntakeEvent: { aggregate: () => Promise.resolve(emptyAggregate()), }, labResult: { aggregate: () => Promise.resolve(emptyAggregate()) }, }, })); vi.mock("@/lib/tz/resolver", () => ({ resolveUserTimezone: () => Promise.resolve("UTC"), })); function emptyAggregate() { return { _count: { _all: 0 }, _min: { startedAt: null, moodLoggedAt: null, scheduledFor: null, takenAt: null, }, _max: { startedAt: null, moodLoggedAt: null, scheduledFor: null, takenAt: null, }, }; } const readCoachCorrelations = vi.fn(); vi.mock("@/lib/ai/coach/tools/correlations-read", () => ({ readCoachCorrelations: (userId: string, locale: string) => readCoachCorrelations(userId, locale), })); // The executor asks for the account's language before it asks for a narrated // correlation, so the sentences it hands the model are not silently English. const resolveLocaleForUser = vi.fn(async (_userId: string) => "de"); vi.mock("@/lib/i18n/user-locale", () => ({ resolveLocaleForUser: (userId: string) => resolveLocaleForUser(userId), })); // v1.21.0 (NEW-B B-2) — the illness-recovery tool augments its snapshot blocks // with the computed retrospective scores. Mock the read-only engine wrapper so // the executor test stays a pure dispatch test. const buildIllnessScores = vi.fn(); vi.mock("@/lib/ai/coach/illness-snapshot", () => ({ buildIllnessScores: (userId: string) => buildIllnessScores(userId), })); import { executeCoachTool } from "@/lib/ai/coach/tools/executor"; function snapshot( sections: Record, referenceGrounding: string | null = null, ): CoachSnapshotResult { return { snapshotJson: JSON.stringify(sections), sections, provenance: { windows: [], metrics: [] }, referenceGrounding, units: DEFAULT_UNIT_PREFERENCES, }; } describe("executeCoachTool", () => { beforeEach(() => { buildCoachSnapshot.mockReset(); readCoachCorrelations.mockReset(); buildIllnessScores.mockReset(); buildIllnessScores.mockResolvedValue(null); }); it("returns the matching section for get_metric_series when present", async () => { buildCoachSnapshot.mockResolvedValue( snapshot( { bloodPressure: { aggregate: { avgSys30: 128 } } }, "REFERENCE GROUNDING\nBP systolic 128 …", ), ); const result = await executeCoachTool({ userId: "u1", name: "get_metric_series", rawArguments: JSON.stringify({ metric: "bp" }), }); expect(result.present).toBe(true); expect(result.data).toMatchObject({ metric: "bp", section: { aggregate: { avgSys30: 128 } }, }); expect(result.grounding).toContain("REFERENCE GROUNDING"); }); it("returns { present: false } (never throws) when the section is absent", async () => { buildCoachSnapshot.mockResolvedValue(snapshot({})); const result = await executeCoachTool({ userId: "u1", name: "get_metric_series", rawArguments: JSON.stringify({ metric: "hrv" }), }); expect(result.present).toBe(false); expect(result.reason).toBe("no_data"); expect(result.data).toBeUndefined(); }); it("points get_metric_series(glucose) at the dedicated tool", async () => { const result = await executeCoachTool({ userId: "u1", name: "get_metric_series", rawArguments: JSON.stringify({ metric: "glucose" }), }); expect(result.present).toBe(false); expect(result.reason).toBe("use_get_glucose_panel"); // Must not even read the snapshot for a wrong-tool call. expect(buildCoachSnapshot).not.toHaveBeenCalled(); }); it("rejects invalid arguments with a grounded miss, not a throw", async () => { const result = await executeCoachTool({ userId: "u1", name: "get_metric_series", rawArguments: JSON.stringify({ metric: "not_a_metric" }), }); expect(result.present).toBe(false); expect(result.reason).toBe("invalid_arguments"); }); it("rejects malformed JSON arguments with a grounded miss", async () => { const result = await executeCoachTool({ userId: "u1", name: "get_metric_series", rawArguments: "{not json", }); expect(result.present).toBe(false); expect(result.reason).toBe("invalid_arguments"); }); it("rejects an unknown tool name without throwing", async () => { const result = await executeCoachTool({ userId: "u1", name: "drop_table_users", rawArguments: "{}", }); expect(result.present).toBe(false); expect(result.reason).toBe("unknown_tool"); expect(buildCoachSnapshot).not.toHaveBeenCalled(); }); it("degrades a snapshot-builder throw to { present: false }", async () => { buildCoachSnapshot.mockRejectedValue(new Error("db down")); const result = await executeCoachTool({ userId: "u1", name: "get_glucose_panel", rawArguments: "{}", }); expect(result.present).toBe(false); expect(result.reason).toBe("retrieval_failed"); }); it("combines sleep nights + rhythm sections", async () => { buildCoachSnapshot.mockResolvedValue( snapshot({ sleep: { timeline: { recent: [] } }, sleepRhythm: { sleepDebt: 120, chronotype: "intermediate" }, }), ); const result = await executeCoachTool({ userId: "u1", name: "get_sleep", rawArguments: "{}", }); expect(result.present).toBe(true); expect(result.data).toMatchObject({ nights: { timeline: { recent: [] } }, rhythm: { sleepDebt: 120 }, }); }); it("surfaces glp1 from weeklyContext on get_medication_compliance", async () => { buildCoachSnapshot.mockResolvedValue( snapshot({ compliance: { rate: 0.92 }, weeklyContext: { glp1: { drug: "—", dose: "—" } }, }), ); const result = await executeCoachTool({ userId: "u1", name: "get_medication_compliance", rawArguments: "{}", }); expect(result.present).toBe(true); expect(result.data).toMatchObject({ compliance: { rate: 0.92 }, glp1: { drug: "—" }, }); }); it("filters labs by analyte and reports analyte_not_found", async () => { buildCoachSnapshot.mockResolvedValue( snapshot({ labs: { recent: [{ name: "LDL", value: "120" }] }, }), ); const hit = await executeCoachTool({ userId: "u1", name: "get_labs", rawArguments: JSON.stringify({ analyte: "ldl" }), }); expect(hit.present).toBe(true); expect(hit.data).toMatchObject({ recent: [{ name: "LDL" }] }); const miss = await executeCoachTool({ userId: "u1", name: "get_labs", rawArguments: JSON.stringify({ analyte: "glucose" }), }); expect(miss.present).toBe(false); expect(miss.reason).toBe("analyte_not_found"); }); // v1.21.0 (NEW-A) — labs must reach the Coach with their value AND unit so it // can cite the reading, not just name the biomarker. The snapshot labs block // already carries { analyte, value, unit, rangeStatus, … }; the tool passes // it through verbatim. This guards that the value + unit survive the tool. it("get_labs carries each reading's value and unit (citation guarantee)", async () => { buildCoachSnapshot.mockResolvedValue( snapshot({ labs: { recent: [ { analyte: "LDL", value: 120, unit: "mg/dL", rangeStatus: "above", referenceLow: null, referenceHigh: 116, takenAt: "2026-06-01T00:00:00.000Z", }, ], }, }), ); const result = await executeCoachTool({ userId: "u1", name: "get_labs", rawArguments: "{}", }); expect(result.present).toBe(true); const data = result.data as { recent: Array<{ value: number; unit: string; rangeStatus: string }>; }; expect(data.recent[0]).toMatchObject({ analyte: "LDL", value: 120, unit: "mg/dL", rangeStatus: "above", }); }); it("returns the workouts section for get_workouts when present", async () => { buildCoachSnapshot.mockResolvedValue( snapshot({ workouts: { recent: [{ sport: "RUN" }], totalInWindow: 3 } }), ); const result = await executeCoachTool({ userId: "u1", name: "get_workouts", rawArguments: JSON.stringify({ window: "last30days" }), }); expect(result.present).toBe(true); expect(result.data).toMatchObject({ totalInWindow: 3 }); }); it("returns { present: false } for get_workouts when no block", async () => { buildCoachSnapshot.mockResolvedValue(snapshot({})); const result = await executeCoachTool({ userId: "u1", name: "get_workouts", rawArguments: "{}", }); expect(result.present).toBe(false); expect(result.reason).toBe("no_data"); }); it("returns the cycle section for get_cycle when present", async () => { buildCoachSnapshot.mockResolvedValue( snapshot({ cycle: { phase: "luteal", dayOfCycle: 21 } }), ); const result = await executeCoachTool({ userId: "u1", name: "get_cycle", rawArguments: "{}", }); expect(result.present).toBe(true); expect(result.data).toMatchObject({ phase: "luteal" }); }); it("returns { present: false } for get_cycle when cycle tracking is off", async () => { // A non-cycle account produces no cycle block (gated in the builder). buildCoachSnapshot.mockResolvedValue(snapshot({})); const result = await executeCoachTool({ userId: "u1", name: "get_cycle", rawArguments: "{}", }); expect(result.present).toBe(false); expect(result.reason).toBe("no_data"); }); it("surfaces discovered drivers + coincident flag for get_correlations", async () => { readCoachCorrelations.mockResolvedValue({ present: true, drivers: [ { behaviour: "time in daylight", outcome: "sleep duration", direction: "higher", lagDays: 1, n: 42, r: 0.31, note: "Higher time in daylight tends to go with higher next-day sleep duration in your data. It is a pattern to watch, not a cause.", }, ], coincident: { fired: false, contributing: [], day: "2026-06-02", illnessExplained: false, }, pairsTested: 18, windowDays: 180, }); const result = await executeCoachTool({ userId: "u1", name: "get_correlations", rawArguments: "{}", }); expect(result.present).toBe(true); expect(result.data).toMatchObject({ drivers: [{ behaviour: "time in daylight", n: 42 }], pairsTested: 18, }); // The account's language reached the reader — the notes are finished // sentences, and an MCP client shows some of them as they stand. expect(readCoachCorrelations).toHaveBeenCalledWith("u1", "de"); }); it("returns a clean { present: false } for get_correlations on no pattern", async () => { readCoachCorrelations.mockResolvedValue({ present: false, reason: "no_significant_pattern", }); const result = await executeCoachTool({ userId: "u1", name: "get_correlations", rawArguments: "{}", }); expect(result.present).toBe(false); expect(result.reason).toBe("no_significant_pattern"); }); it("never passes userId as a tool argument (read from session only)", async () => { buildCoachSnapshot.mockResolvedValue(snapshot({})); // A crafted argument trying to smuggle a userId must be rejected by the // strict schema, never forwarded to the read. const result = await executeCoachTool({ userId: "u1", name: "get_metric_series", rawArguments: JSON.stringify({ metric: "bp", userId: "victim" }), }); expect(result.present).toBe(false); expect(result.reason).toBe("invalid_arguments"); }); // v1.21.0 (NEW-B B-2) — get_illness_recovery now carries the computed // retrospective scores the illness card shows (recovery-gap, gap-driver, // nadir, pre-onset, red flags), not just labels + composites. it("get_illness_recovery surfaces the computed illness scores", async () => { buildCoachSnapshot.mockResolvedValue( snapshot({ illness: { restMode: true, active: [], recentResolved: [] } }), ); buildIllnessScores.mockResolvedValue({ episodeLabel: "flu", episodeType: "INFECTION", state: "resolved", recoveryGapDays: 4, gapDriverType: "RESTING_HEART_RATE", nadir: [ { type: "HEART_RATE_VARIABILITY", day: "2026-06-10", deviationSd: -2.4, direction: "below", }, ], preOnset: [], redFlags: [ { type: "BODY_TEMPERATURE", reason: "sustained_fever", worstValue: 38.9, days: 3, }, ], }); const result = await executeCoachTool({ userId: "u1", name: "get_illness_recovery", rawArguments: "{}", }); expect(result.present).toBe(true); const data = result.data as { illnessScores?: Record }; expect(data.illnessScores).toMatchObject({ recoveryGapDays: 4, gapDriverType: "RESTING_HEART_RATE", }); expect(data.illnessScores?.redFlags).toHaveLength(1); expect(data.illnessScores?.nadir).toHaveLength(1); }); it("get_illness_recovery is present on scores alone (no derived blocks)", async () => { // No illness/derived/strain/trajectory section, but the engine returned // scores → the tool must still report present and carry them. buildCoachSnapshot.mockResolvedValue(snapshot({})); buildIllnessScores.mockResolvedValue({ episodeLabel: "cold", episodeType: "INFECTION", state: "active", recoveryGapDays: null, gapDriverType: null, nadir: [], preOnset: [], redFlags: [], }); const result = await executeCoachTool({ userId: "u1", name: "get_illness_recovery", rawArguments: "{}", }); expect(result.present).toBe(true); expect( (result.data as { illnessScores?: unknown }).illnessScores, ).toBeTruthy(); }); }); // v1.21.0 (D5-1) — ONE snapshot per turn. When the route threads the shared // full-source scope (the inventory's probe scope) and the tool's window // matches, the tool must read under the SHARED scope key so every per-tool read // lands the inventory's already-built 60s LRU entry — rather than rebuilding a // distinct single-source snapshot per tool. describe("executeCoachTool — shared snapshot scope (D5-1)", () => { beforeEach(() => { buildCoachSnapshot.mockReset(); }); const sharedScope = { sources: ["bp", "hrv", "sleep", "glucose"] as never, window: "last30days" as const, }; it("reads under the shared scope when the tool window matches", async () => { buildCoachSnapshot.mockResolvedValue( snapshot({ bloodPressure: { aggregate: { avgSys30: 128 } } }), ); const result = await executeCoachTool({ userId: "u1", name: "get_metric_series", rawArguments: JSON.stringify({ metric: "bp" }), fallbackWindow: "last30days", sharedScope, }); expect(result.present).toBe(true); // The read used the SHARED scope object, not a narrow single-source scope — // so a second tool with the same shared scope hits the same cache key. expect(buildCoachSnapshot).toHaveBeenCalledWith("u1", sharedScope); }); it("two tools in a turn read under the SAME scope key (one build)", async () => { buildCoachSnapshot.mockResolvedValue( snapshot({ bloodPressure: { aggregate: {} }, heartRateVariability: { aggregate: {} }, }), ); await executeCoachTool({ userId: "u1", name: "get_metric_series", rawArguments: JSON.stringify({ metric: "bp" }), fallbackWindow: "last30days", sharedScope, }); await executeCoachTool({ userId: "u1", name: "get_metric_series", rawArguments: JSON.stringify({ metric: "hrv" }), fallbackWindow: "last30days", sharedScope, }); // Both reads used the identical shared scope object → identical cache key. const scopes = buildCoachSnapshot.mock.calls.map((c) => c[1]); expect(scopes).toHaveLength(2); expect(scopes[0]).toBe(sharedScope); expect(scopes[1]).toBe(sharedScope); }); it("falls back to a narrow scope when the tool overrides the window", async () => { buildCoachSnapshot.mockResolvedValue( snapshot({ bloodPressure: { aggregate: {} } }), ); await executeCoachTool({ userId: "u1", name: "get_metric_series", // The model overrides the window → a distinct, correct build. rawArguments: JSON.stringify({ metric: "bp", window: "last7days" }), fallbackWindow: "last30days", sharedScope, }); expect(buildCoachSnapshot).toHaveBeenCalledWith("u1", { sources: ["bp"], window: "last7days", }); }); });