@task-mcp/shared 1.0.7 → 1.0.9

package/src/schemas/response-schema.test.ts

@@ -0,0 +1,314 @@
+import { describe, expect, it } from "bun:test";
+import {
+  ResponseType,
+  ResponsePriority,
+  ResponseOption,
+  QuestionResponse,
+  SuggestionResponse,
+  ConfirmationResponse,
+  GenerateResponseInput,
+} from "./response-schema.js";
+
+describe("Response Schema", () => {
+  describe("ResponseType", () => {
+    it("should accept valid response types", () => {
+      expect(() => ResponseType.parse("question")).not.toThrow();
+      expect(() => ResponseType.parse("suggestion")).not.toThrow();
+      expect(() => ResponseType.parse("confirmation")).not.toThrow();
+    });
+
+    it("should reject invalid response types", () => {
+      expect(() => ResponseType.parse("invalid")).toThrow();
+      expect(() => ResponseType.parse("ask")).toThrow();
+    });
+  });
+
+  describe("ResponsePriority", () => {
+    it("should accept valid priority levels", () => {
+      expect(() => ResponsePriority.parse("low")).not.toThrow();
+      expect(() => ResponsePriority.parse("medium")).not.toThrow();
+      expect(() => ResponsePriority.parse("high")).not.toThrow();
+      expect(() => ResponsePriority.parse("critical")).not.toThrow();
+    });
+
+    it("should reject invalid priority levels", () => {
+      expect(() => ResponsePriority.parse("urgent")).toThrow();
+      expect(() => ResponsePriority.parse("normal")).toThrow();
+    });
+  });
+
+  describe("ResponseOption", () => {
+    it("should validate option with all fields", () => {
+      const option = {
+        label: "High Priority",
+        value: "high",
+        description: "For urgent tasks",
+      };
+
+      expect(() => ResponseOption.parse(option)).not.toThrow();
+      const parsed = ResponseOption.parse(option);
+      expect(parsed.label).toBe("High Priority");
+      expect(parsed.value).toBe("high");
+      expect(parsed.description).toBe("For urgent tasks");
+    });
+
+    it("should validate option without description", () => {
+      const option = {
+        label: "Low Priority",
+        value: "low",
+      };
+
+      expect(() => ResponseOption.parse(option)).not.toThrow();
+      const parsed = ResponseOption.parse(option);
+      expect(parsed.label).toBe("Low Priority");
+      expect(parsed.value).toBe("low");
+      expect(parsed.description).toBeUndefined();
+    });
+
+    it("should reject option without required fields", () => {
+      expect(() => ResponseOption.parse({ label: "Test" })).toThrow();
+      expect(() => ResponseOption.parse({ value: "test" })).toThrow();
+      expect(() => ResponseOption.parse({})).toThrow();
+    });
+  });
+
+  describe("QuestionResponse", () => {
+    it("should validate question with all fields", () => {
+      const question = {
+        type: "question" as const,
+        message: "What should we do?",
+        context: "Need clarification on approach",
+        priority: "high" as const,
+        options: [
+          { label: "Option A", value: "a" },
+          { label: "Option B", value: "b" },
+        ],
+        defaultOption: "a",
+      };
+
+      expect(() => QuestionResponse.parse(question)).not.toThrow();
+      const parsed = QuestionResponse.parse(question);
+      expect(parsed.type).toBe("question");
+      expect(parsed.message).toBe("What should we do?");
+      expect(parsed.options).toHaveLength(2);
+      expect(parsed.defaultOption).toBe("a");
+    });
+
+    it("should validate question with minimal fields", () => {
+      const question = {
+        type: "question" as const,
+        message: "Proceed?",
+      };
+
+      expect(() => QuestionResponse.parse(question)).not.toThrow();
+      const parsed = QuestionResponse.parse(question);
+      expect(parsed.type).toBe("question");
+      expect(parsed.message).toBe("Proceed?");
+      expect(parsed.context).toBeUndefined();
+      expect(parsed.options).toBeUndefined();
+    });
+
+    it("should reject question without message", () => {
+      expect(() => QuestionResponse.parse({ type: "question" })).toThrow();
+    });
+
+    it("should reject question with wrong type", () => {
+      expect(() =>
+        QuestionResponse.parse({
+          type: "suggestion",
+          message: "Test",
+        })
+      ).toThrow();
+    });
+  });
+
+  describe("SuggestionResponse", () => {
+    it("should validate suggestion with all fields", () => {
+      const suggestion = {
+        type: "suggestion" as const,
+        message: "Consider breaking down this task",
+        context: "Task is complex",
+        priority: "medium" as const,
+        options: [
+          { label: "3 subtasks", value: "sub_3" },
+          { label: "5 subtasks", value: "sub_5" },
+        ],
+        reasoning: "Based on complexity analysis",
+      };
+
+      expect(() => SuggestionResponse.parse(suggestion)).not.toThrow();
+      const parsed = SuggestionResponse.parse(suggestion);
+      expect(parsed.type).toBe("suggestion");
+      expect(parsed.options).toHaveLength(2);
+      expect(parsed.reasoning).toBe("Based on complexity analysis");
+    });
+
+    it("should validate suggestion with minimal fields", () => {
+      const suggestion = {
+        type: "suggestion" as const,
+        message: "Try this",
+        options: [{ label: "Do it", value: "yes" }],
+      };
+
+      expect(() => SuggestionResponse.parse(suggestion)).not.toThrow();
+      const parsed = SuggestionResponse.parse(suggestion);
+      expect(parsed.options).toHaveLength(1);
+    });
+
+    it("should reject suggestion without options", () => {
+      expect(() =>
+        SuggestionResponse.parse({
+          type: "suggestion",
+          message: "Test",
+        })
+      ).toThrow();
+    });
+
+    it("should reject suggestion with empty options array", () => {
+      expect(() =>
+        SuggestionResponse.parse({
+          type: "suggestion",
+          message: "Test",
+          options: [],
+        })
+      ).toThrow();
+    });
+  });
+
+  describe("ConfirmationResponse", () => {
+    it("should validate confirmation with all fields", () => {
+      const confirmation = {
+        type: "confirmation" as const,
+        message: "Are you sure?",
+        action: "Delete all completed tasks",
+        context: "This operation is irreversible",
+        priority: "critical" as const,
+        consequences: ["10 tasks will be removed", "Cannot be undone"],
+        defaultConfirm: false,
+      };
+
+      expect(() => ConfirmationResponse.parse(confirmation)).not.toThrow();
+      const parsed = ConfirmationResponse.parse(confirmation);
+      expect(parsed.type).toBe("confirmation");
+      expect(parsed.action).toBe("Delete all completed tasks");
+      expect(parsed.consequences).toHaveLength(2);
+      expect(parsed.defaultConfirm).toBe(false);
+    });
+
+    it("should validate confirmation with minimal fields", () => {
+      const confirmation = {
+        type: "confirmation" as const,
+        message: "Delete this?",
+        action: "Delete task",
+      };
+
+      expect(() => ConfirmationResponse.parse(confirmation)).not.toThrow();
+      const parsed = ConfirmationResponse.parse(confirmation);
+      expect(parsed.action).toBe("Delete task");
+      expect(parsed.consequences).toBeUndefined();
+    });
+
+    it("should reject confirmation without action", () => {
+      expect(() =>
+        ConfirmationResponse.parse({
+          type: "confirmation",
+          message: "Confirm?",
+        })
+      ).toThrow();
+    });
+
+    it("should reject confirmation without message", () => {
+      expect(() =>
+        ConfirmationResponse.parse({
+          type: "confirmation",
+          action: "Do something",
+        })
+      ).toThrow();
+    });
+  });
+
+  describe("GenerateResponseInput", () => {
+    it("should validate input for question type", () => {
+      const input = {
+        type: "question" as const,
+        message: "What to do?",
+        options: [{ label: "Yes", value: "yes" }],
+        defaultOption: "yes",
+      };
+
+      expect(() => GenerateResponseInput.parse(input)).not.toThrow();
+      const parsed = GenerateResponseInput.parse(input);
+      expect(parsed.type).toBe("question");
+    });
+
+    it("should validate input for suggestion type", () => {
+      const input = {
+        type: "suggestion" as const,
+        message: "Try this",
+        options: [{ label: "Option", value: "opt" }],
+        reasoning: "Because reasons",
+      };
+
+      expect(() => GenerateResponseInput.parse(input)).not.toThrow();
+    });
+
+    it("should validate input for confirmation type", () => {
+      const input = {
+        type: "confirmation" as const,
+        message: "Sure?",
+        action: "Delete",
+        consequences: ["Gone forever"],
+        defaultConfirm: false,
+      };
+
+      expect(() => GenerateResponseInput.parse(input)).not.toThrow();
+    });
+
+    it("should use default priority of medium", () => {
+      const input = {
+        type: "question" as const,
+        message: "Test?",
+      };
+
+      const parsed = GenerateResponseInput.parse(input);
+      expect(parsed.priority).toBe("medium");
+    });
+
+    it("should allow custom priority", () => {
+      const input = {
+        type: "question" as const,
+        message: "Test?",
+        priority: "critical" as const,
+      };
+
+      const parsed = GenerateResponseInput.parse(input);
+      expect(parsed.priority).toBe("critical");
+    });
+  });
+
+  describe("Type discrimination", () => {
+    it("should differentiate response types at compile time", () => {
+      const question: QuestionResponse = {
+        type: "question",
+        message: "Test",
+      };
+
+      const suggestion: SuggestionResponse = {
+        type: "suggestion",
+        message: "Test",
+        options: [{ label: "A", value: "a" }],
+      };
+
+      const confirmation: ConfirmationResponse = {
+        type: "confirmation",
+        message: "Test",
+        action: "Do it",
+      };
+
+      // TypeScript should allow this
+      expect(question.type).toBe("question");
+      expect(suggestion.type).toBe("suggestion");
+      expect(confirmation.type).toBe("confirmation");
+    });
+  });
+});

package/src/schemas/response-schema.ts

@@ -0,0 +1,92 @@
+import { z } from "zod";
+
+/**
+ * Response Schema
+ *
+ * Standardized formats for AI agents to ask questions, make suggestions,
+ * or request confirmation from users.
+ */
+
+// Response types
+export const ResponseType = z.enum(["question", "suggestion", "confirmation"]);
+export type ResponseType = z.infer<typeof ResponseType>;
+
+// Priority level for responses
+export const ResponsePriority = z.enum(["low", "medium", "high", "critical"]);
+export type ResponsePriority = z.infer<typeof ResponsePriority>;
+
+// Option for multiple choice responses
+export const ResponseOption = z.object({
+  label: z.string().describe("Display text for the option"),
+  value: z.string().describe("Value to return when selected"),
+  description: z.string().optional().describe("Additional explanation"),
+});
+export type ResponseOption = z.infer<typeof ResponseOption>;
+
+// Base response schema
+const BaseResponse = z.object({
+  type: ResponseType.describe("Type of response: question, suggestion, or confirmation"),
+  message: z.string().describe("Main message to display to user"),
+  context: z.string().optional().describe("Additional context or explanation"),
+  priority: ResponsePriority.optional().describe("Urgency/importance of response (default: medium)"),
+});
+
+// Question response - for clarification
+export const QuestionResponse = BaseResponse.extend({
+  type: z.literal("question"),
+  options: z.array(ResponseOption).optional()
+    .describe("Multiple choice options (omit for free-form answer)"),
+  defaultOption: z.string().optional()
+    .describe("Default option value if user provides no input"),
+});
+export type QuestionResponse = z.infer<typeof QuestionResponse>;
+
+// Suggestion response - for recommendations
+export const SuggestionResponse = BaseResponse.extend({
+  type: z.literal("suggestion"),
+  options: z.array(ResponseOption).min(1)
+    .describe("Suggested options for user to choose from"),
+  reasoning: z.string().optional()
+    .describe("Explanation of why these suggestions were made"),
+});
+export type SuggestionResponse = z.infer<typeof SuggestionResponse>;
+
+// Confirmation response - for explicit approval
+export const ConfirmationResponse = BaseResponse.extend({
+  type: z.literal("confirmation"),
+  action: z.string().describe("Action that will be taken if confirmed"),
+  consequences: z.array(z.string()).optional()
+    .describe("List of effects or changes that will occur"),
+  defaultConfirm: z.boolean().optional()
+    .describe("Default choice if user provides no input (default: false)"),
+});
+export type ConfirmationResponse = z.infer<typeof ConfirmationResponse>;
+
+// Union type for all response types
+export const AgentResponse = z.discriminatedUnion("type", [
+  QuestionResponse,
+  SuggestionResponse,
+  ConfirmationResponse,
+]);
+export type AgentResponse = z.infer<typeof AgentResponse>;
+
+// Input schema for generating responses
+export const GenerateResponseInput = z.object({
+  type: ResponseType.describe("Type of response to generate"),
+  message: z.string().describe("Main message"),
+  options: z.array(ResponseOption).optional()
+    .describe("Options for question/suggestion types"),
+  context: z.string().optional(),
+  priority: ResponsePriority.optional().default("medium"),
+  action: z.string().optional()
+    .describe("Action description (for confirmation type)"),
+  consequences: z.array(z.string()).optional()
+    .describe("Consequences list (for confirmation type)"),
+  reasoning: z.string().optional()
+    .describe("Reasoning explanation (for suggestion type)"),
+  defaultOption: z.string().optional()
+    .describe("Default option value (for question type)"),
+  defaultConfirm: z.boolean().optional()
+    .describe("Default confirmation choice (for confirmation type)"),
+});
+export type GenerateResponseInput = z.infer<typeof GenerateResponseInput>;