retestkit 1.4.1

package/src/elicitation/index.test.ts

@@ -0,0 +1,399 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createElicitationClient, ElicitationType } from "./index.js";
+import type { Logger } from "../logger.js";
+import type { ClientCapabilities } from "../types/capabilities.js";
+import type { ElicitationRequest, ElicitationResponse } from "./types.js";
+
+describe("elicitation", () => {
+  let mockLogger: Logger;
+
+  beforeEach(() => {
+    mockLogger = {
+      debug: vi.fn(),
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      setLevel: vi.fn(),
+      withCorrelation: vi.fn().mockReturnThis(),
+    } as unknown as Logger;
+  });
+
+  const capabilitiesWithElicitation: ClientCapabilities = {
+    sampling: true,
+    elicitation: true,
+    logging: false,
+    progress: true,
+    resourcesListChanged: false,
+    resourcesSubscribe: false,
+    protocolVersion: "2025-06-18",
+  };
+
+  const capabilitiesWithoutElicitation: ClientCapabilities = {
+    sampling: true,
+    elicitation: false,
+    logging: false,
+    progress: true,
+    resourcesListChanged: false,
+    resourcesSubscribe: false,
+    protocolVersion: "2025-06-18",
+  };
+
+  describe("createElicitationClient", () => {
+    it("reports elicitation availability correctly", () => {
+      const clientWith = createElicitationClient(
+        vi.fn(),
+        capabilitiesWithElicitation,
+        mockLogger
+      );
+
+      const clientWithout = createElicitationClient(
+        vi.fn(),
+        capabilitiesWithoutElicitation,
+        mockLogger
+      );
+
+      expect(clientWith.hasElicitation()).toBe(true);
+      expect(clientWithout.hasElicitation()).toBe(false);
+    });
+  });
+
+  describe("elicit", () => {
+    it("returns fallback when elicitation unavailable", async () => {
+      const requestElicitation = vi.fn();
+      const client = createElicitationClient(
+        requestElicitation,
+        capabilitiesWithoutElicitation,
+        mockLogger
+      );
+
+      const request: ElicitationRequest = {
+        type: ElicitationType.CookieConsent,
+        title: "Cookie Banner",
+        message: "A cookie banner was detected",
+        options: [{ value: "accept", label: "Accept all" }],
+      };
+
+      const result = await client.elicit(request);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe("Elicitation not available");
+      expect(result.fallbackQuestions).toBeDefined();
+      expect(requestElicitation).not.toHaveBeenCalled();
+    });
+
+    it("blocks credential elicitation requests", async () => {
+      const requestElicitation = vi.fn();
+      const client = createElicitationClient(
+        requestElicitation,
+        capabilitiesWithElicitation,
+        mockLogger
+      );
+
+      const request: ElicitationRequest = {
+        type: ElicitationType.AuthRequired,
+        title: "Auth Required",
+        message: "Please authenticate",
+        options: [
+          { value: "enter_password", label: "Enter your password" },
+          { value: "skip", label: "Skip" },
+        ],
+      };
+
+      const result = await client.elicit(request);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe("Security policy prevents credential elicitation");
+      expect(requestElicitation).not.toHaveBeenCalled();
+      expect(mockLogger.error).toHaveBeenCalledWith(
+        "Attempted to elicit credentials - blocked",
+        expect.any(Object)
+      );
+    });
+
+    it("handles user cancel action", async () => {
+      const mockResponse: ElicitationResponse = {
+        action: "cancel",
+      };
+
+      const requestElicitation = vi.fn().mockResolvedValue(mockResponse);
+      const client = createElicitationClient(
+        requestElicitation,
+        capabilitiesWithElicitation,
+        mockLogger
+      );
+
+      const request: ElicitationRequest = {
+        type: ElicitationType.CookieConsent,
+        title: "Cookie Banner",
+        message: "A cookie banner was detected",
+        options: [{ value: "accept", label: "Accept all" }],
+      };
+
+      const result = await client.elicit(request);
+
+      expect(result.success).toBe(true);
+      expect(result.cancelled).toBe(true);
+    });
+
+    it("handles user dismiss action", async () => {
+      const mockResponse: ElicitationResponse = {
+        action: "dismiss",
+      };
+
+      const requestElicitation = vi.fn().mockResolvedValue(mockResponse);
+      const client = createElicitationClient(
+        requestElicitation,
+        capabilitiesWithElicitation,
+        mockLogger
+      );
+
+      const request: ElicitationRequest = {
+        type: ElicitationType.ModalBlocking,
+        title: "Modal",
+        message: "A modal is blocking",
+        options: [{ value: "close", label: "Close" }],
+      };
+
+      const result = await client.elicit(request);
+
+      expect(result.success).toBe(true);
+      expect(result.selectedValue).toBe("dismiss");
+    });
+
+    it("extracts selected value from response", async () => {
+      const mockResponse: ElicitationResponse = {
+        action: "submit",
+        content: { selected: "accept_all" },
+      };
+
+      const requestElicitation = vi.fn().mockResolvedValue(mockResponse);
+      const client = createElicitationClient(
+        requestElicitation,
+        capabilitiesWithElicitation,
+        mockLogger
+      );
+
+      const request: ElicitationRequest = {
+        type: ElicitationType.CookieConsent,
+        title: "Cookie Banner",
+        message: "A cookie banner was detected",
+        options: [{ value: "accept_all", label: "Accept all" }],
+      };
+
+      const result = await client.elicit(request);
+
+      expect(result.success).toBe(true);
+      expect(result.selectedValue).toBe("accept_all");
+    });
+
+    it("extracts custom value from response", async () => {
+      const mockResponse: ElicitationResponse = {
+        action: "submit",
+        content: { custom: "/custom/path" },
+      };
+
+      const requestElicitation = vi.fn().mockResolvedValue(mockResponse);
+      const client = createElicitationClient(
+        requestElicitation,
+        capabilitiesWithElicitation,
+        mockLogger
+      );
+
+      const request: ElicitationRequest = {
+        type: ElicitationType.AmbiguousNavigation,
+        title: "Multiple options",
+        message: "Which path?",
+        options: [],
+        allowCustom: true,
+      };
+
+      const result = await client.elicit(request);
+
+      expect(result.success).toBe(true);
+      expect(result.customValue).toBe("/custom/path");
+    });
+
+    it("handles request errors gracefully", async () => {
+      const requestElicitation = vi
+        .fn()
+        .mockRejectedValue(new Error("Connection failed"));
+
+      const client = createElicitationClient(
+        requestElicitation,
+        capabilitiesWithElicitation,
+        mockLogger
+      );
+
+      const request: ElicitationRequest = {
+        type: ElicitationType.CookieConsent,
+        title: "Cookie Banner",
+        message: "A cookie banner was detected",
+        options: [{ value: "accept", label: "Accept" }],
+      };
+
+      const result = await client.elicit(request);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe("Connection failed");
+      expect(result.fallbackQuestions).toBeDefined();
+    });
+  });
+
+  describe("createCookieConsentRequest", () => {
+    it("creates properly structured request", () => {
+      const client = createElicitationClient(
+        vi.fn(),
+        capabilitiesWithElicitation,
+        mockLogger
+      );
+
+      const request = client.createCookieConsentRequest(
+        "GDPR banner with accept/reject buttons"
+      );
+
+      expect(request.type).toBe(ElicitationType.CookieConsent);
+      expect(request.title).toBe("Cookie Consent Banner Detected");
+      expect(request.message).toContain("GDPR banner");
+      expect(request.options.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe("createModalBlockingRequest", () => {
+    it("creates properly structured request", () => {
+      const client = createElicitationClient(
+        vi.fn(),
+        capabilitiesWithElicitation,
+        mockLogger
+      );
+
+      const request = client.createModalBlockingRequest(
+        "Sign up for our newsletter to get 10% off!"
+      );
+
+      expect(request.type).toBe(ElicitationType.ModalBlocking);
+      expect(request.title).toBe("Modal Dialog Blocking Page");
+      expect(request.message).toContain("Sign up");
+      expect(request.options.length).toBeGreaterThan(0);
+    });
+
+    it("truncates long modal content", () => {
+      const client = createElicitationClient(
+        vi.fn(),
+        capabilitiesWithElicitation,
+        mockLogger
+      );
+
+      const longContent = "A".repeat(500);
+      const request = client.createModalBlockingRequest(longContent);
+
+      expect(request.message.length).toBeLessThan(500);
+      expect(request.message).toContain("...");
+    });
+  });
+
+  describe("createAmbiguousNavigationRequest", () => {
+    it("creates properly structured request", () => {
+      const client = createElicitationClient(
+        vi.fn(),
+        capabilitiesWithElicitation,
+        mockLogger
+      );
+
+      const options = [
+        { url: "/products", label: "Products" },
+        { url: "/services", label: "Services" },
+        { url: "/about", label: "About Us" },
+      ];
+
+      const request = client.createAmbiguousNavigationRequest(options);
+
+      expect(request.type).toBe(ElicitationType.AmbiguousNavigation);
+      expect(request.title).toBe("Multiple Navigation Options");
+      expect(request.options.length).toBe(3);
+      expect(request.options[0].value).toBe("/products");
+      expect(request.options[0].label).toBe("Products");
+      expect(request.allowCustom).toBe(true);
+    });
+
+    it("limits options to 5 maximum", () => {
+      const client = createElicitationClient(
+        vi.fn(),
+        capabilitiesWithElicitation,
+        mockLogger
+      );
+
+      const options = Array.from({ length: 10 }, (_, i) => ({
+        url: `/path${i}`,
+        label: `Option ${i}`,
+      }));
+
+      const request = client.createAmbiguousNavigationRequest(options);
+
+      expect(request.options.length).toBe(5);
+    });
+
+    it("uses default labels when not provided", () => {
+      const client = createElicitationClient(
+        vi.fn(),
+        capabilitiesWithElicitation,
+        mockLogger
+      );
+
+      const options = [
+        { url: "/path1", label: "" },
+        { url: "/path2", label: "" },
+      ];
+
+      const request = client.createAmbiguousNavigationRequest(options);
+
+      expect(request.options[0].label).toBe("Option 1");
+      expect(request.options[1].label).toBe("Option 2");
+    });
+  });
+
+  describe("createAuthRequiredRequest", () => {
+    it("creates properly structured request", () => {
+      const client = createElicitationClient(
+        vi.fn(),
+        capabilitiesWithElicitation,
+        mockLogger
+      );
+
+      const request = client.createAuthRequiredRequest();
+
+      expect(request.type).toBe(ElicitationType.AuthRequired);
+      expect(request.title).toBe("Authentication Required");
+      expect(request.message).toContain("security reasons");
+      expect(request.message).toContain("cannot handle login automatically");
+      expect(request.options.length).toBeGreaterThan(0);
+    });
+
+    it("does not include credential entry options", () => {
+      const client = createElicitationClient(
+        vi.fn(),
+        capabilitiesWithElicitation,
+        mockLogger
+      );
+
+      const request = client.createAuthRequiredRequest();
+
+      const hasCredentialOption = request.options.some(
+        (opt) =>
+          opt.value.includes("password") ||
+          opt.value.includes("credential") ||
+          opt.value.includes("login")
+      );
+
+      expect(hasCredentialOption).toBe(false);
+    });
+  });
+
+  describe("ElicitationType enum", () => {
+    it("has expected values", () => {
+      expect(ElicitationType.CookieConsent).toBe("cookie_consent");
+      expect(ElicitationType.ModalBlocking).toBe("modal_blocking");
+      expect(ElicitationType.AmbiguousNavigation).toBe("ambiguous_navigation");
+      expect(ElicitationType.AuthRequired).toBe("auth_required");
+    });
+  });
+});

package/src/elicitation/index.ts

@@ -0,0 +1,171 @@
+import type { Logger } from "../logger.js";
+import type { ClientCapabilities } from "../types/capabilities.js";
+import { isElicitationSupported } from "../types/capabilities.js";
+import {
+  type ElicitationRequest,
+  type ElicitationResponse,
+  type ElicitationResult,
+  ElicitationType,
+  COOKIE_CONSENT_OPTIONS,
+  MODAL_BLOCKING_OPTIONS,
+  AUTH_REQUIRED_OPTIONS,
+} from "./types.js";
+
+export * from "./types.js";
+
+export interface ElicitationClient {
+  elicit(request: ElicitationRequest): Promise<ElicitationResult>;
+  hasElicitation(): boolean;
+  createCookieConsentRequest(context: string): ElicitationRequest;
+  createModalBlockingRequest(modalContent: string): ElicitationRequest;
+  createAmbiguousNavigationRequest(
+    options: Array<{ url: string; label: string }>
+  ): ElicitationRequest;
+  createAuthRequiredRequest(): ElicitationRequest;
+}
+
+export function createElicitationClient(
+  requestElicitation: (
+    request: ElicitationRequest
+  ) => Promise<ElicitationResponse>,
+  capabilities: ClientCapabilities,
+  logger: Logger
+): ElicitationClient {
+  const hasElicitationCapability = isElicitationSupported(capabilities);
+
+  async function elicit(
+    request: ElicitationRequest
+  ): Promise<ElicitationResult> {
+    // Validate that we never request credentials
+    if (request.type === ElicitationType.AuthRequired) {
+      // Ensure options don't include credential entry
+      const hasCredentialOption = request.options.some(
+        (opt) =>
+          opt.value.includes("password") ||
+          opt.value.includes("credential") ||
+          opt.value.includes("login")
+      );
+
+      if (hasCredentialOption) {
+        logger.error("Attempted to elicit credentials - blocked", {
+          type: request.type,
+        });
+        return {
+          success: false,
+          error: "Security policy prevents credential elicitation",
+        };
+      }
+    }
+
+    // If elicitation not available, return fallback
+    if (!hasElicitationCapability) {
+      logger.info("Elicitation unavailable, returning fallback questions");
+
+      return {
+        success: false,
+        error: "Elicitation not available",
+        fallbackQuestions: request,
+      };
+    }
+
+    logger.debug("Sending elicitation request", {
+      type: request.type,
+      title: request.title,
+      optionCount: request.options.length,
+    });
+
+    try {
+      const response = await requestElicitation(request);
+
+      if (response.action === "cancel") {
+        logger.info("User cancelled elicitation", { type: request.type });
+        return {
+          success: true,
+          cancelled: true,
+        };
+      }
+
+      if (response.action === "dismiss") {
+        logger.info("User dismissed elicitation", { type: request.type });
+        return {
+          success: true,
+          selectedValue: "dismiss",
+        };
+      }
+
+      // Extract selected value from content
+      const selectedValue = response.content?.selected || response.content?.value;
+
+      logger.info("Elicitation response received", {
+        type: request.type,
+        action: response.action,
+        selectedValue,
+      });
+
+      return {
+        success: true,
+        selectedValue,
+        customValue: response.content?.custom,
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      logger.error("Elicitation request failed", { error: message });
+
+      return {
+        success: false,
+        error: message,
+        fallbackQuestions: request,
+      };
+    }
+  }
+
+  return {
+    elicit,
+    hasElicitation: () => hasElicitationCapability,
+
+    createCookieConsentRequest(context: string): ElicitationRequest {
+      return {
+        type: ElicitationType.CookieConsent,
+        title: "Cookie Consent Banner Detected",
+        message: `A cookie consent banner was detected on the page. How should we handle it?\n\nContext: ${context}`,
+        options: COOKIE_CONSENT_OPTIONS,
+      };
+    },
+
+    createModalBlockingRequest(modalContent: string): ElicitationRequest {
+      return {
+        type: ElicitationType.ModalBlocking,
+        title: "Modal Dialog Blocking Page",
+        message: `A modal dialog is blocking page interaction.\n\nModal content: ${modalContent.slice(0, 200)}...`,
+        options: MODAL_BLOCKING_OPTIONS,
+      };
+    },
+
+    createAmbiguousNavigationRequest(
+      options: Array<{ url: string; label: string }>
+    ): ElicitationRequest {
+      return {
+        type: ElicitationType.AmbiguousNavigation,
+        title: "Multiple Navigation Options",
+        message:
+          "Multiple similar navigation options were found. Which path should we explore?",
+        options: options.slice(0, 5).map((opt, i) => ({
+          value: opt.url,
+          label: opt.label || `Option ${i + 1}`,
+          description: opt.url,
+        })),
+        allowCustom: true,
+      };
+    },
+
+    createAuthRequiredRequest(): ElicitationRequest {
+      return {
+        type: ElicitationType.AuthRequired,
+        title: "Authentication Required",
+        message:
+          "This page requires authentication. For security reasons, we cannot handle login automatically. How would you like to proceed?",
+        options: AUTH_REQUIRED_OPTIONS,
+      };
+    },
+  };
+}

package/src/elicitation/types.ts

@@ -0,0 +1,68 @@
+export enum ElicitationType {
+  CookieConsent = "cookie_consent",
+  ModalBlocking = "modal_blocking",
+  AmbiguousNavigation = "ambiguous_navigation",
+  AuthRequired = "auth_required",
+  ConfirmAction = "confirm_action",
+}
+
+export interface ElicitationOption {
+  value: string;
+  label: string;
+  description?: string;
+}
+
+export interface ElicitationRequest {
+  type: ElicitationType;
+  title: string;
+  message: string;
+  options: ElicitationOption[];
+  allowCustom?: boolean;
+}
+
+export interface ElicitationResponse {
+  action: "confirm" | "dismiss" | "cancel";
+  content?: Record<string, string>;
+}
+
+export interface ElicitationResult {
+  success: boolean;
+  selectedValue?: string;
+  customValue?: string;
+  cancelled?: boolean;
+  error?: string;
+  fallbackQuestions?: ElicitationRequest;
+}
+
+// Predefined option sets for common scenarios
+export const COOKIE_CONSENT_OPTIONS: ElicitationOption[] = [
+  { value: "accept", label: "Accept All", description: "Accept all cookies" },
+  {
+    value: "reject",
+    label: "Reject All",
+    description: "Reject non-essential cookies",
+  },
+  {
+    value: "dismiss",
+    label: "Dismiss",
+    description: "Close the banner without choosing",
+  },
+];
+
+export const MODAL_BLOCKING_OPTIONS: ElicitationOption[] = [
+  { value: "close", label: "Close Modal", description: "Close and continue" },
+  {
+    value: "interact",
+    label: "Interact",
+    description: "Interact with modal content",
+  },
+];
+
+export const AUTH_REQUIRED_OPTIONS: ElicitationOption[] = [
+  { value: "stop", label: "Stop Analysis", description: "End the analysis" },
+  {
+    value: "continue",
+    label: "Continue Unauthenticated",
+    description: "Continue without logging in",
+  },
+];