feat(KB-225): add AI text refinement feature to dashboard

- Add AI text refinement backend service with OpenAI/Anthropic integration
- Add /api/refine-text API endpoint with error handling
- Add QuickEntryBox AI refine button with style presets menu
- Add NewTaskModal AI refine feature for task description editing
- Add comprehensive tests for backend service, API, and components
- Add changeset for the new feature

packages/dashboard/app/api.test.ts

@@ -1172,3 +1172,127 @@ describe("API Error Handling", () => {
     });
   });
 });
+
+// ── AI Text Refinement API Tests ───────────────────────────────────────────
+
+import { refineText, getRefineErrorMessage, REFINE_ERROR_MESSAGES, type RefinementType } from "./api";
+
+describe("refineText", () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it("sends POST with text and type, returns refined text", async () => {
+    globalThis.fetch = vi.fn().mockReturnValue(
+      mockFetchResponse(true, { refined: "Refined task description" })
+    );
+
+    const result = await refineText("Original text", "clarify");
+
+    expect(result).toBe("Refined task description");
+    expect(globalThis.fetch).toHaveBeenCalledWith("/api/ai/refine-text", {
+      headers: { "Content-Type": "application/json" },
+      method: "POST",
+      body: JSON.stringify({ text: "Original text", type: "clarify" }),
+    });
+  });
+
+  it("works with all four refinement types", async () => {
+    globalThis.fetch = vi.fn().mockReturnValue(
+      mockFetchResponse(true, { refined: "Refined" })
+    );
+
+    const types: RefinementType[] = ["clarify", "add-details", "expand", "simplify"];
+
+    for (const type of types) {
+      const result = await refineText("Test text", type);
+      expect(result).toBe("Refined");
+    }
+  });
+
+  it("throws on rate limit error (429)", async () => {
+    globalThis.fetch = vi.fn().mockReturnValue(
+      mockFetchResponse(false, { error: "Rate limit exceeded. Maximum 10 refinement requests per hour." }, 429)
+    );
+
+    await expect(refineText("Test", "clarify")).rejects.toThrow("Rate limit exceeded");
+  });
+
+  it("throws on invalid type error (422)", async () => {
+    globalThis.fetch = vi.fn().mockReturnValue(
+      mockFetchResponse(false, { error: "type must be one of: clarify, add-details, expand, simplify" }, 422)
+    );
+
+    await expect(refineText("Test", "invalid" as RefinementType)).rejects.toThrow("type must be one of");
+  });
+
+  it("throws on validation error (400)", async () => {
+    globalThis.fetch = vi.fn().mockReturnValue(
+      mockFetchResponse(false, { error: "text must be at least 1 character" }, 400)
+    );
+
+    await expect(refineText("", "clarify")).rejects.toThrow("text must be at least 1 character");
+  });
+
+  it("throws on server error (500)", async () => {
+    globalThis.fetch = vi.fn().mockReturnValue(
+      mockFetchResponse(false, { error: "AI service error" }, 500)
+    );
+
+    await expect(refineText("Test", "clarify")).rejects.toThrow("AI service error");
+  });
+});
+
+describe("getRefineErrorMessage", () => {
+  it("returns rate limit message for rate limit errors", () => {
+    const error = new Error("Rate limit exceeded");
+    expect(getRefineErrorMessage(error)).toBe(REFINE_ERROR_MESSAGES.RATE_LIMIT);
+  });
+
+  it("returns rate limit message for 429 status", () => {
+    const error = new Error("429 Too Many Requests");
+    expect(getRefineErrorMessage(error)).toBe(REFINE_ERROR_MESSAGES.RATE_LIMIT);
+  });
+
+  it("returns invalid type message for invalid type errors", () => {
+    const error = new Error("Invalid type selected");
+    expect(getRefineErrorMessage(error)).toBe(REFINE_ERROR_MESSAGES.INVALID_TYPE);
+  });
+
+  it("passes through text validation errors", () => {
+    const error = new Error("text must be at least 1 character");
+    expect(getRefineErrorMessage(error)).toBe("text must be at least 1 character");
+  });
+
+  it("passes through text length errors", () => {
+    const error = new Error("text must not exceed 2000 characters");
+    expect(getRefineErrorMessage(error)).toBe("text must not exceed 2000 characters");
+  });
+
+  it("passes through type required errors", () => {
+    const error = new Error("type is required");
+    expect(getRefineErrorMessage(error)).toBe("type is required");
+  });
+
+  it("returns network message for unknown errors", () => {
+    const error = new Error("Network failure");
+    expect(getRefineErrorMessage(error)).toBe(REFINE_ERROR_MESSAGES.NETWORK);
+  });
+
+  it("returns network message for non-Error values", () => {
+    expect(getRefineErrorMessage("string error")).toBe(REFINE_ERROR_MESSAGES.NETWORK);
+    expect(getRefineErrorMessage(null)).toBe(REFINE_ERROR_MESSAGES.NETWORK);
+    expect(getRefineErrorMessage(undefined)).toBe(REFINE_ERROR_MESSAGES.NETWORK);
+  });
+});
+
+describe("REFINE_ERROR_MESSAGES", () => {
+  it("has the expected error messages", () => {
+    expect(REFINE_ERROR_MESSAGES.RATE_LIMIT).toBe("Too many refinement requests. Please wait an hour.");
+    expect(REFINE_ERROR_MESSAGES.INVALID_TYPE).toBe("Invalid refinement option selected.");
+    expect(REFINE_ERROR_MESSAGES.NETWORK).toBe("Failed to refine text. Please try again.");
+  });
+});
+

packages/dashboard/app/api.ts

@@ -1180,3 +1180,76 @@ export function refineWorkflowStepPrompt(id: string): Promise<{ prompt: string;
     method: "POST",
   });
 }
+
+// ── AI Text Refinement API ────────────────────────────────────────────
+
+/** Refinement types for AI text refinement */
+export type RefinementType = "clarify" | "add-details" | "expand" | "simplify";
+
+/** Response from text refinement endpoint */
+export interface RefineTextResponse {
+  refined: string;
+}
+
+/**
+ * Refine task description text using AI.
+ * @param text - The text to refine (1-2000 characters)
+ * @param type - The refinement type: clarify, add-details, expand, or simplify
+ * @returns The refined text
+ * @throws Error with message for rate limit (429), invalid type (422), validation (400), or server errors
+ */
+export async function refineText(text: string, type: RefinementType): Promise<string> {
+  const response = await api<RefineTextResponse>("/ai/refine-text", {
+    method: "POST",
+    body: JSON.stringify({ text, type }),
+  });
+  return response.refined;
+}
+
+/**
+ * Error messages for refineText failures (to use with toast notifications).
+ */
+export const REFINE_ERROR_MESSAGES = {
+  /** Rate limit exceeded (429) */
+  RATE_LIMIT: "Too many refinement requests. Please wait an hour.",
+  /** Invalid refinement type (422) */
+  INVALID_TYPE: "Invalid refinement option selected.",
+  /** Network or server errors */
+  NETWORK: "Failed to refine text. Please try again.",
+} as const;
+
+/**
+ * Get user-friendly error message for a refineText error.
+ * @param error - The error thrown by refineText
+ * @returns A user-friendly error message suitable for toast display
+ */
+export function getRefineErrorMessage(error: unknown): string {
+  if (!(error instanceof Error)) {
+    return REFINE_ERROR_MESSAGES.NETWORK;
+  }
+
+  const message = error.message.toLowerCase();
+
+  // Rate limit errors (429)
+  if (message.includes("rate limit") || message.includes("429")) {
+    return REFINE_ERROR_MESSAGES.RATE_LIMIT;
+  }
+
+  // Invalid type errors (422)
+  if (message.includes("invalid") && message.includes("type")) {
+    return REFINE_ERROR_MESSAGES.INVALID_TYPE;
+  }
+
+  // Text validation errors (400) - pass through from backend
+  if (
+    message.startsWith("text must") ||
+    message.includes("text is required") ||
+    message.includes("type is required")
+  ) {
+    return error.message;
+  }
+
+  // Default network/server error
+  return REFINE_ERROR_MESSAGES.NETWORK;
+}
+

packages/dashboard/app/components/NewTaskModal.tsx

@@ -1,11 +1,12 @@
 import { useState, useCallback, useEffect, useRef, useMemo } from "react";
 import type { Task, TaskCreateInput, ModelPreset, Settings, WorkflowStep } from "@kb/core";
 import type { ToastType } from "../hooks/useToast";
-import { uploadAttachment, fetchModels, fetchSettings, fetchWorkflowSteps } from "../api";
+import { uploadAttachment, fetchModels, fetchSettings, fetchWorkflowSteps, refineText, getRefineErrorMessage, type RefinementType } from "../api";
 import type { ModelInfo } from "../api";
 import { filterModels } from "../utils/modelFilter";
 import { applyPresetToSelection, getRecommendedPresetForSize } from "../utils/modelPresets";
 import { ProviderIcon } from "./ProviderIcon";
+import { Sparkles } from "lucide-react";
 
 const ALLOWED_IMAGE_TYPES = ["image/png", "image/jpeg", "image/gif", "image/webp"];
 
@@ -320,6 +321,11 @@ export function NewTaskModal({ isOpen, onClose, tasks, onCreateTask, addToast, o
   const [workflowSteps, setWorkflowSteps] = useState<WorkflowStep[]>([]);
   const [selectedWorkflowSteps, setSelectedWorkflowSteps] = useState<string[]>([]);
 
+  // AI Refinement state
+  const [isRefineMenuOpen, setIsRefineMenuOpen] = useState(false);
+  const [isRefining, setIsRefining] = useState(false);
+  const refineMenuRef = useRef<HTMLDivElement>(null);
+
   const depDropdownRef = useRef<HTMLDivElement>(null);
   const descTextareaRef = useRef<HTMLTextAreaElement>(null);
   const fileInputRef = useRef<HTMLInputElement>(null);
@@ -392,6 +398,18 @@ export function NewTaskModal({ isOpen, onClose, tasks, onCreateTask, addToast, o
     return () => document.removeEventListener("mousedown", handleClickOutside);
   }, [showDepDropdown]);
 
+  // Close refine menu when clicking outside
+  useEffect(() => {
+    if (!isRefineMenuOpen) return;
+    const handleClickOutside = (e: MouseEvent) => {
+      if (refineMenuRef.current && !refineMenuRef.current.contains(e.target as Node)) {
+        setIsRefineMenuOpen(false);
+      }
+    };
+    document.addEventListener("mousedown", handleClickOutside);
+    return () => document.removeEventListener("mousedown", handleClickOutside);
+  }, [isRefineMenuOpen]);
+
   // Handle paste for images
   const handlePaste = useCallback((e: React.ClipboardEvent) => {
     const items = e.clipboardData?.items;
@@ -462,6 +480,8 @@ export function NewTaskModal({ isOpen, onClose, tasks, onCreateTask, addToast, o
     setPresetMode("default");
     setEnablePlanningMode(false);
     setSelectedWorkflowSteps([]);
+    setIsRefineMenuOpen(false);
+    setIsRefining(false);
     setHasDirtyState(false);
     onClose();
   }, [hasDirtyState, onClose, pendingImages]);
@@ -568,6 +588,30 @@ export function NewTaskModal({ isOpen, onClose, tasks, onCreateTask, addToast, o
     el.style.height = el.scrollHeight + "px";
   }, []);
 
+  // AI Refinement handler
+  const handleRefine = useCallback(async (type: RefinementType) => {
+    const trimmed = description.trim();
+    if (!trimmed || isRefining) return;
+
+    setIsRefining(true);
+    try {
+      const refined = await refineText(trimmed, type);
+      setDescription(refined);
+      setIsRefineMenuOpen(false);
+      addToast("Description refined with AI", "success");
+      // Auto-resize textarea after content update
+      if (descTextareaRef.current) {
+        descTextareaRef.current.style.height = "auto";
+        descTextareaRef.current.style.height = descTextareaRef.current.scrollHeight + "px";
+      }
+    } catch (err: any) {
+      const errorMessage = getRefineErrorMessage(err);
+      addToast(errorMessage, "error");
+    } finally {
+      setIsRefining(false);
+    }
+  }, [description, isRefining, addToast]);
+
   if (!isOpen) return null;
 
   const availableDeps = tasks
@@ -608,15 +652,69 @@ export function NewTaskModal({ isOpen, onClose, tasks, onCreateTask, addToast, o
           {/* Description field */}
           <div className="form-group">
             <label htmlFor="new-task-description">Description</label>
-            <textarea
-              ref={descTextareaRef}
-              id="new-task-description"
-              value={description}
-              onChange={handleDescriptionChange}
-              placeholder="What needs to be done?"
-              rows={3}
-              disabled={isSubmitting}
-            />
+            <div className="description-with-refine" ref={refineMenuRef}>
+              <textarea
+                ref={descTextareaRef}
+                id="new-task-description"
+                value={description}
+                onChange={handleDescriptionChange}
+                placeholder="What needs to be done?"
+                rows={3}
+                disabled={isSubmitting || isRefining}
+              />
+              {description.trim() && !isSubmitting && (
+                <button
+                  type="button"
+                  className={`btn btn-sm refine-button ${isRefining ? "refine-button--loading" : ""}`}
+                  onClick={() => setIsRefineMenuOpen((prev) => !prev)}
+                  disabled={isRefining}
+                  data-testid="refine-button"
+                  title="Refine description with AI"
+                >
+                  <Sparkles size={12} style={{ verticalAlign: "middle" }} />
+                  {isRefining ? "Refining..." : "Refine"}
+                </button>
+              )}
+              {isRefineMenuOpen && (
+                <div
+                  className="refine-menu refine-menu--modal"
+                  onMouseDown={(e) => e.preventDefault()}
+                >
+                  <div
+                    className="refine-menu-item"
+                    onClick={() => handleRefine("clarify")}
+                    data-testid="refine-clarify"
+                  >
+                    <div className="refine-menu-item-title">Clarify</div>
+                    <div className="refine-menu-item-desc">Make the description clearer and more specific</div>
+                  </div>
+                  <div
+                    className="refine-menu-item"
+                    onClick={() => handleRefine("add-details")}
+                    data-testid="refine-add-details"
+                  >
+                    <div className="refine-menu-item-title">Add details</div>
+                    <div className="refine-menu-item-desc">Add implementation details and context</div>
+                  </div>
+                  <div
+                    className="refine-menu-item"
+                    onClick={() => handleRefine("expand")}
+                    data-testid="refine-expand"
+                  >
+                    <div className="refine-menu-item-title">Expand</div>
+                    <div className="refine-menu-item-desc">Expand into a more comprehensive description</div>
+                  </div>
+                  <div
+                    className="refine-menu-item"
+                    onClick={() => handleRefine("simplify")}
+                    data-testid="refine-simplify"
+                  >
+                    <div className="refine-menu-item-title">Simplify</div>
+                    <div className="refine-menu-item-desc">Simplify and make more concise</div>
+                  </div>
+                </div>
+              )}
+            </div>
           </div>
 
           {/* Dependencies */}

packages/dashboard/app/components/QuickEntryBox.tsx

@@ -1,9 +1,9 @@
 import { useState, useCallback, useRef, useEffect } from "react";
 import type { ToastType } from "../hooks/useToast";
 import type { Task, TaskCreateInput } from "@kb/core";
-import type { ModelInfo } from "../api";
-import { fetchModels } from "../api";
-import { Link, Brain, Lightbulb, ListTree } from "lucide-react";
+import type { ModelInfo, RefinementType } from "../api";
+import { fetchModels, refineText, getRefineErrorMessage } from "../api";
+import { Link, Brain, Lightbulb, ListTree, Sparkles } from "lucide-react";
 import { CustomModelDropdown } from "./CustomModelDropdown";
 
 const STORAGE_KEY = "kb-quick-entry-text";
@@ -69,6 +69,11 @@ export function QuickEntryBox({ onCreate, addToast, tasks = [], availableModels,
   const [modelsError, setModelsError] = useState<string | null>(null);
   const [loadedModels, setLoadedModels] = useState<ModelInfo[]>(availableModels ?? []);
 
+  // AI Refinement state
+  const [isRefineMenuOpen, setIsRefineMenuOpen] = useState(false);
+  const [isRefining, setIsRefining] = useState(false);
+  const refineMenuRef = useRef<HTMLDivElement>(null);
+
   // If onCreate is not provided, the component is disabled
   const isDisabled = !onCreate;
 
@@ -173,6 +178,20 @@ export function QuickEntryBox({ onCreate, addToast, tasks = [], availableModels,
     if (!showDeps) setDepSearch("");
   }, [showDeps]);
 
+  // Close refine menu when clicking outside
+  useEffect(() => {
+    if (!isRefineMenuOpen) return;
+
+    const handleClickOutside = (e: MouseEvent) => {
+      if (refineMenuRef.current && !refineMenuRef.current.contains(e.target as Node)) {
+        setIsRefineMenuOpen(false);
+      }
+    };
+
+    document.addEventListener("mousedown", handleClickOutside);
+    return () => document.removeEventListener("mousedown", handleClickOutside);
+  }, [isRefineMenuOpen]);
+
   const resetForm = useCallback(() => {
     setDescription("");
     setDependencies([]);
@@ -182,6 +201,8 @@ export function QuickEntryBox({ onCreate, addToast, tasks = [], availableModels,
     setValidatorModelId(undefined);
     setShowDeps(false);
     setShowModels(false);
+    setIsRefineMenuOpen(false);
+    setIsRefining(false);
     setIsExpanded(false);
     justResetRef.current = true;
     if (textareaRef.current) {
@@ -246,9 +267,10 @@ export function QuickEntryBox({ onCreate, addToast, tasks = [], availableModels,
       } else if (e.key === "Escape") {
         e.preventDefault();
         // Close dropdowns first if open
-        if (showDeps || showModels) {
+        if (showDeps || showModels || isRefineMenuOpen) {
           setShowDeps(false);
           setShowModels(false);
+          setIsRefineMenuOpen(false);
           return;
         }
         // Clear non-empty input on Escape and clear localStorage
@@ -273,7 +295,7 @@ export function QuickEntryBox({ onCreate, addToast, tasks = [], availableModels,
         textareaRef.current?.blur();
       }
     },
-    [handleSubmit, description, isExpanded, showDeps, showModels, resetForm],
+    [handleSubmit, description, isExpanded, showDeps, showModels, isRefineMenuOpen, resetForm],
   );
 
   const handleFocus = useCallback(() => {
@@ -294,7 +316,7 @@ export function QuickEntryBox({ onCreate, addToast, tasks = [], availableModels,
     // Collapse after a short delay to allow click events on dropdowns
     // Collapse regardless of content - only check if dropdowns are open
     blurTimeoutRef.current = setTimeout(() => {
-      if (!showDeps && !showModels) {
+      if (!showDeps && !showModels && !isRefineMenuOpen) {
         setIsExpanded(false);
         // Reset height when collapsing
         if (textareaRef.current) {
@@ -303,7 +325,7 @@ export function QuickEntryBox({ onCreate, addToast, tasks = [], availableModels,
       }
       blurTimeoutRef.current = null;
     }, 200);
-  }, [showDeps, showModels]);
+  }, [showDeps, showModels, isRefineMenuOpen]);
 
   const toggleDep = useCallback((id: string) => {
     setDependencies((prev) =>
@@ -372,6 +394,29 @@ export function QuickEntryBox({ onCreate, addToast, tasks = [], availableModels,
     resetForm();
   }, [description, onSubtaskBreakdown, addToast, resetForm]);
 
+  const handleRefine = useCallback(async (type: RefinementType) => {
+    const trimmed = description.trim();
+    if (!trimmed || isRefining) return;
+
+    setIsRefining(true);
+    try {
+      const refined = await refineText(trimmed, type);
+      setDescription(refined);
+      setIsRefineMenuOpen(false);
+      addToast("Description refined with AI", "success");
+      // Auto-resize textarea after content update
+      if (textareaRef.current) {
+        textareaRef.current.style.height = "auto";
+        textareaRef.current.style.height = `${Math.min(textareaRef.current.scrollHeight, 200)}px`;
+      }
+    } catch (err: any) {
+      const errorMessage = getRefineErrorMessage(err);
+      addToast(errorMessage, "error");
+    } finally {
+      setIsRefining(false);
+    }
+  }, [description, isRefining, addToast]);
+
   const truncate = (s: string, len: number) =>
     s.length > len ? s.slice(0, len) + "…" : s;
 
@@ -574,6 +619,58 @@ export function QuickEntryBox({ onCreate, addToast, tasks = [], availableModels,
                   <ListTree size={12} style={{ verticalAlign: "middle" }} />
                   Subtask
                 </button>
+                <div className="refine-trigger-wrap" ref={refineMenuRef}>
+                  <button
+                    type="button"
+                    className={`btn btn-sm refine-button ${isRefining ? "refine-button--loading" : ""}`}
+                    onClick={() => setIsRefineMenuOpen((prev) => !prev)}
+                    disabled={!description.trim() || isRefining}
+                    data-testid="refine-button"
+                    title="Refine description with AI"
+                  >
+                    <Sparkles size={12} style={{ verticalAlign: "middle" }} />
+                    {isRefining ? "Refining..." : "Refine"}
+                  </button>
+                  {isRefineMenuOpen && (
+                    <div
+                      className="refine-menu"
+                      onMouseDown={(e) => e.preventDefault()}
+                    >
+                      <div
+                        className="refine-menu-item"
+                        onClick={() => handleRefine("clarify")}
+                        data-testid="refine-clarify"
+                      >
+                        <div className="refine-menu-item-title">Clarify</div>
+                        <div className="refine-menu-item-desc">Make the description clearer and more specific</div>
+                      </div>
+                      <div
+                        className="refine-menu-item"
+                        onClick={() => handleRefine("add-details")}
+                        data-testid="refine-add-details"
+                      >
+                        <div className="refine-menu-item-title">Add details</div>
+                        <div className="refine-menu-item-desc">Add implementation details and context</div>
+                      </div>
+                      <div
+                        className="refine-menu-item"
+                        onClick={() => handleRefine("expand")}
+                        data-testid="refine-expand"
+                      >
+                        <div className="refine-menu-item-title">Expand</div>
+                        <div className="refine-menu-item-desc">Expand into a more comprehensive description</div>
+                      </div>
+                      <div
+                        className="refine-menu-item"
+                        onClick={() => handleRefine("simplify")}
+                        data-testid="refine-simplify"
+                      >
+                        <div className="refine-menu-item-title">Simplify</div>
+                        <div className="refine-menu-item-desc">Simplify and make more concise</div>
+                      </div>
+                    </div>
+                  )}
+                </div>
               </>
             )}
           </div>

packages/dashboard/app/components/__tests__/NewTaskModal.test.tsx

@@ -17,6 +17,8 @@ vi.mock("../../api", () => ({
     defaultPresetBySize: {},
   }),
   fetchWorkflowSteps: vi.fn().mockResolvedValue([]),
+  refineText: vi.fn(),
+  getRefineErrorMessage: vi.fn((err) => err?.message || "Failed to refine text. Please try again."),
 }));
 
 function makeTask(id: string): Task {
@@ -537,4 +539,133 @@ describe("NewTaskModal", () => {
       );
     });
   });
+
+  describe("AI Refine feature", () => {
+    it("shows refine button when description has content", async () => {
+      renderNewTaskModal();
+      const textarea = screen.getByLabelText(/Description/i);
+
+      // Initially, refine button is not visible
+      expect(screen.queryByTestId("refine-button")).toBeNull();
+
+      // Type something
+      fireEvent.change(textarea, { target: { value: "Task to refine" } });
+
+      // Now the refine button should be visible
+      await waitFor(() => {
+        expect(screen.getByTestId("refine-button")).toBeTruthy();
+      });
+    });
+
+    it("hides refine button when description is empty", async () => {
+      renderNewTaskModal();
+      const textarea = screen.getByLabelText(/Description/i);
+
+      // Type something first
+      fireEvent.change(textarea, { target: { value: "Some text" } });
+      await waitFor(() => {
+        expect(screen.getByTestId("refine-button")).toBeTruthy();
+      });
+
+      // Clear the input
+      fireEvent.change(textarea, { target: { value: "" } });
+
+      // Button should be hidden
+      expect(screen.queryByTestId("refine-button")).toBeNull();
+    });
+
+    it("opens refine menu on button click", async () => {
+      renderNewTaskModal();
+      const textarea = screen.getByLabelText(/Description/i);
+
+      fireEvent.change(textarea, { target: { value: "Task to refine" } });
+      await waitFor(() => {
+        expect(screen.getByTestId("refine-button")).toBeTruthy();
+      });
+
+      fireEvent.click(screen.getByTestId("refine-button"));
+
+      // Menu should be visible with all options
+      expect(screen.getByTestId("refine-clarify")).toBeTruthy();
+      expect(screen.getByTestId("refine-add-details")).toBeTruthy();
+      expect(screen.getByTestId("refine-expand")).toBeTruthy();
+      expect(screen.getByTestId("refine-simplify")).toBeTruthy();
+    });
+
+    it("successful refinement updates description and shows toast", async () => {
+      const { refineText } = await import("../../api");
+      vi.mocked(refineText).mockResolvedValueOnce("Refined description");
+
+      const { props } = renderNewTaskModal();
+      const textarea = screen.getByLabelText(/Description/i);
+
+      fireEvent.change(textarea, { target: { value: "Original text" } });
+      await waitFor(() => {
+        expect(screen.getByTestId("refine-button")).toBeTruthy();
+      });
+
+      fireEvent.click(screen.getByTestId("refine-button"));
+      fireEvent.click(screen.getByTestId("refine-clarify"));
+
+      await waitFor(() => {
+        expect(refineText).toHaveBeenCalledWith("Original text", "clarify");
+      });
+
+      // Textarea should be updated
+      await waitFor(() => {
+        expect(textarea).toHaveValue("Refined description");
+      });
+
+      // Success toast should be shown
+      await waitFor(() => {
+        expect(props.addToast).toHaveBeenCalledWith("Description refined with AI", "success");
+      });
+    });
+
+    it("shows error toast on refinement failure and preserves original text", async () => {
+      const { refineText, getRefineErrorMessage } = await import("../../api");
+      vi.mocked(refineText).mockRejectedValueOnce(new Error("Rate limit exceeded"));
+      vi.mocked(getRefineErrorMessage).mockReturnValue("Too many refinement requests. Please wait an hour.");
+
+      const { props } = renderNewTaskModal();
+      const textarea = screen.getByLabelText(/Description/i);
+
+      fireEvent.change(textarea, { target: { value: "Original text" } });
+      await waitFor(() => {
+        expect(screen.getByTestId("refine-button")).toBeTruthy();
+      });
+
+      fireEvent.click(screen.getByTestId("refine-button"));
+      fireEvent.click(screen.getByTestId("refine-clarify"));
+
+      await waitFor(() => {
+        expect(props.addToast).toHaveBeenCalledWith("Too many refinement requests. Please wait an hour.", "error");
+      });
+
+      // Original text should be preserved
+      expect(textarea).toHaveValue("Original text");
+    });
+
+    it("shows loading state during refinement", async () => {
+      const { refineText } = await import("../../api");
+      // Slow down the promise to see loading state
+      vi.mocked(refineText).mockImplementation(() => new Promise((resolve) => setTimeout(() => resolve("Refined"), 100)));
+
+      renderNewTaskModal();
+      const textarea = screen.getByLabelText(/Description/i);
+
+      fireEvent.change(textarea, { target: { value: "Original text" } });
+      await waitFor(() => {
+        expect(screen.getByTestId("refine-button")).toBeTruthy();
+      });
+
+      fireEvent.click(screen.getByTestId("refine-button"));
+      fireEvent.click(screen.getByTestId("refine-expand"));
+
+      // Button should show loading text
+      await waitFor(() => {
+        expect(screen.getByText("Refining...")).toBeTruthy();
+      });
+    });
+  });
 });

packages/dashboard/app/components/__tests__/QuickEntryBox.test.tsx

@@ -65,6 +65,8 @@ vi.mock("../../api", () => ({
       contextWindow: 128_000,
     },
   ]),
+  refineText: vi.fn(),
+  getRefineErrorMessage: vi.fn((err) => err?.message || "Failed to refine text. Please try again."),
 }));
 
 // Mock lucide-react
@@ -73,6 +75,7 @@ vi.mock("lucide-react", () => ({
   Brain: () => null,
   Lightbulb: () => null,
   ListTree: () => null,
+  Sparkles: () => null,
 }));
 
 function renderQuickEntryBox(props = {}) {
@@ -713,4 +716,211 @@ describe("QuickEntryBox", () => {
       expect(localStorage.getItem("kb-quick-entry-text")).toBe("Task with dropdown");
     });
   });
+
+  describe("AI Refine feature", () => {
+    it("shows refine button when text is entered", () => {
+      renderQuickEntryBox();
+      const textarea = screen.getByTestId("quick-entry-input");
+
+      // Initially, refine button is not visible
+      expect(screen.queryByTestId("refine-button")).toBeNull();
+
+      // Focus and type something
+      fireEvent.focus(textarea);
+      fireEvent.change(textarea, { target: { value: "Task to refine" } });
+
+      // Now the refine button should be visible
+      expect(screen.getByTestId("refine-button")).toBeTruthy();
+    });
+
+    it("refine button is hidden when textarea is empty", () => {
+      renderQuickEntryBox();
+      const textarea = screen.getByTestId("quick-entry-input");
+
+      // Focus and type something
+      fireEvent.focus(textarea);
+      fireEvent.change(textarea, { target: { value: "Some text" } });
+      expect(screen.getByTestId("refine-button")).toBeTruthy();
+
+      // Clear the input
+      fireEvent.change(textarea, { target: { value: "" } });
+
+      // Button should be hidden/disabled (might be hidden when controls collapse)
+      const refineButton = screen.queryByTestId("refine-button");
+      if (refineButton) {
+        expect((refineButton as HTMLButtonElement).disabled).toBe(true);
+      }
+    });
+
+    it("opens refine menu on button click", () => {
+      renderQuickEntryBox();
+      const textarea = screen.getByTestId("quick-entry-input");
+
+      fireEvent.focus(textarea);
+      fireEvent.change(textarea, { target: { value: "Task to refine" } });
+      fireEvent.click(screen.getByTestId("refine-button"));
+
+      // Menu should be visible with all options
+      expect(screen.getByTestId("refine-clarify")).toBeTruthy();
+      expect(screen.getByTestId("refine-add-details")).toBeTruthy();
+      expect(screen.getByTestId("refine-expand")).toBeTruthy();
+      expect(screen.getByTestId("refine-simplify")).toBeTruthy();
+    });
+
+    it("closes refine menu on Escape key", () => {
+      renderQuickEntryBox();
+      const textarea = screen.getByTestId("quick-entry-input");
+
+      fireEvent.focus(textarea);
+      fireEvent.change(textarea, { target: { value: "Task to refine" } });
+      fireEvent.click(screen.getByTestId("refine-button"));
+
+      // Menu should be open
+      expect(screen.getByTestId("refine-clarify")).toBeTruthy();
+
+      // Press Escape
+      fireEvent.keyDown(textarea, { key: "Escape" });
+
+      // Menu should be closed but input preserved
+      expect(screen.queryByTestId("refine-clarify")).toBeNull();
+      expect((textarea as HTMLTextAreaElement).value).toBe("Task to refine");
+    });
+
+    it("closes refine menu when option is selected", async () => {
+      const { refineText } = await import("../../api");
+      vi.mocked(refineText).mockResolvedValueOnce("Refined description");
+
+      renderQuickEntryBox();
+      const textarea = screen.getByTestId("quick-entry-input");
+
+      fireEvent.focus(textarea);
+      fireEvent.change(textarea, { target: { value: "Original text" } });
+      fireEvent.click(screen.getByTestId("refine-button"));
+
+      // Menu should be open
+      expect(screen.getByTestId("refine-clarify")).toBeTruthy();
+
+      // Click on an option
+      fireEvent.click(screen.getByTestId("refine-clarify"));
+
+      // Menu should close
+      await waitFor(() => {
+        expect(screen.queryByTestId("refine-clarify")).toBeNull();
+      });
+    });
+
+    it("successful refinement updates textarea content", async () => {
+      const { refineText } = await import("../../api");
+      vi.mocked(refineText).mockResolvedValueOnce("Refined description");
+
+      const { props } = renderQuickEntryBox();
+      const textarea = screen.getByTestId("quick-entry-input");
+
+      fireEvent.focus(textarea);
+      fireEvent.change(textarea, { target: { value: "Original text" } });
+      fireEvent.click(screen.getByTestId("refine-button"));
+      fireEvent.click(screen.getByTestId("refine-clarify"));
+
+      await waitFor(() => {
+        expect(refineText).toHaveBeenCalledWith("Original text", "clarify");
+      });
+
+      // Textarea should be updated
+      await waitFor(() => {
+        expect((textarea as HTMLTextAreaElement).value).toBe("Refined description");
+      });
+
+      // Success toast should be shown
+      await waitFor(() => {
+        expect(props.addToast).toHaveBeenCalledWith("Description refined with AI", "success");
+      });
+    });
+
+    it("failed refinement shows toast and preserves original text", async () => {
+      const { refineText } = await import("../../api");
+      vi.mocked(refineText).mockRejectedValueOnce(new Error("Rate limit exceeded"));
+
+      const { getRefineErrorMessage } = await import("../../api");
+
+      const { props } = renderQuickEntryBox();
+      const textarea = screen.getByTestId("quick-entry-input");
+
+      fireEvent.focus(textarea);
+      fireEvent.change(textarea, { target: { value: "Original text" } });
+      fireEvent.click(screen.getByTestId("refine-button"));
+      fireEvent.click(screen.getByTestId("refine-clarify"));
+
+      await waitFor(() => {
+        expect(props.addToast).toHaveBeenCalled();
+      });
+
+      // Original text should be preserved
+      expect((textarea as HTMLTextAreaElement).value).toBe("Original text");
+    });
+
+    it("loading state disables button during refinement", async () => {
+      const { refineText } = await import("../../api");
+      // Slow down the promise to see loading state
+      vi.mocked(refineText).mockImplementation(() => new Promise((resolve) => setTimeout(resolve, 100)));
+
+      renderQuickEntryBox();
+      const textarea = screen.getByTestId("quick-entry-input");
+
+      fireEvent.focus(textarea);
+      fireEvent.change(textarea, { target: { value: "Original text" } });
+      fireEvent.click(screen.getByTestId("refine-button"));
+      fireEvent.click(screen.getByTestId("refine-clarify"));
+
+      // Button should show loading text
+      await waitFor(() => {
+        expect(screen.getByText("Refining...")).toBeTruthy();
+      });
+
+      // Button should be disabled
+      const refineButton = screen.getByTestId("refine-button");
+      expect((refineButton as HTMLButtonElement).disabled).toBe(true);
+    });
+
+    it("auto-resizes textarea after refinement", async () => {
+      const { refineText } = await import("../../api");
+      vi.mocked(refineText).mockResolvedValueOnce("Refined description with much more content here");
+
+      renderQuickEntryBox();
+      const textarea = screen.getByTestId("quick-entry-input");
+
+      fireEvent.focus(textarea);
+      fireEvent.change(textarea, { target: { value: "Short" } });
+      fireEvent.click(screen.getByTestId("refine-button"));
+      fireEvent.click(screen.getByTestId("refine-expand"));
+
+      await waitFor(() => {
+        expect(refineText).toHaveBeenCalled();
+      });
+    });
+
+    it("resets refine state when form is reset after creation", async () => {
+      const { refineText } = await import("../../api");
+      vi.mocked(refineText).mockResolvedValueOnce("Refined text");
+
+      const { props } = renderQuickEntryBox();
+      const textarea = screen.getByTestId("quick-entry-input");
+
+      // Open refine menu but don't select anything
+      fireEvent.focus(textarea);
+      fireEvent.change(textarea, { target: { value: "Task" } });
+      fireEvent.click(screen.getByTestId("refine-button"));
+
+      expect(screen.getByTestId("refine-clarify")).toBeTruthy();
+
+      // Submit the form
+      fireEvent.keyDown(textarea, { key: "Enter" });
+
+      await waitFor(() => {
+        expect(props.onCreate).toHaveBeenCalled();
+      });
+
+      // After reset, refine menu should be closed
+      expect(screen.queryByTestId("refine-clarify")).toBeNull();
+    });
+  });
 });

packages/dashboard/app/styles.css

@@ -2355,6 +2355,86 @@ body {
   white-space: nowrap;
 }
 
+/* === AI Refine Menu === */
+.refine-trigger-wrap {
+  position: relative;
+}
+
+.refine-menu {
+  position: absolute;
+  top: 100%;
+  left: 0;
+  margin-top: 4px;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
+  min-width: 200px;
+  max-width: 280px;
+  z-index: 100;
+  overflow: hidden;
+}
+
+.refine-button {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+}
+
+.refine-button--loading {
+  opacity: 0.7;
+  cursor: not-allowed;
+}
+
+.refine-menu-item {
+  padding: 10px 14px;
+  cursor: pointer;
+  transition: background 0.1s ease;
+  border-bottom: 1px solid var(--border);
+}
+
+.refine-menu-item:last-child {
+  border-bottom: none;
+}
+
+.refine-menu-item:hover {
+  background: var(--card-hover);
+}
+
+.refine-menu-item-title {
+  font-weight: 500;
+  font-size: 13px;
+  color: var(--text);
+  margin-bottom: 2px;
+}
+
+.refine-menu-item-desc {
+  font-size: 12px;
+  color: var(--text-muted);
+  line-height: 1.4;
+}
+
+/* NewTaskModal description with refine button */
+.description-with-refine {
+  position: relative;
+}
+
+.description-with-refine .refine-button {
+  position: absolute;
+  top: 8px;
+  right: 8px;
+}
+
+.description-with-refine textarea {
+  padding-right: 70px; /* Make room for the refine button */
+}
+
+.refine-menu--modal {
+  right: 0;
+  left: auto;
+  top: calc(100% + 4px);
+}
+
 .inline-create-model-dropdown {
   position: absolute;
   top: 100%;

packages/dashboard/src/ai-refine.test.ts

@@ -0,0 +1,285 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import {
+  refineText,
+  validateRefineRequest,
+  checkRateLimit,
+  getRateLimitResetTime,
+  __resetRefineState,
+  ValidationError,
+  InvalidTypeError,
+  AiServiceError,
+  VALID_REFINEMENT_TYPES,
+  MIN_TEXT_LENGTH,
+  MAX_TEXT_LENGTH,
+  MAX_REQUESTS_PER_HOUR,
+  RATE_LIMIT_WINDOW_MS,
+} from "./ai-refine.js";
+
+describe("ai-refine module", () => {
+  beforeEach(() => {
+    vi.useFakeTimers({ shouldAdvanceTime: true });
+    __resetRefineState();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe("VALID_REFINEMENT_TYPES", () => {
+    it("contains all four refinement types", () => {
+      expect(VALID_REFINEMENT_TYPES).toEqual([
+        "clarify",
+        "add-details",
+        "expand",
+        "simplify",
+      ]);
+    });
+  });
+
+  describe("validateRefineRequest", () => {
+    it("accepts valid text and 'clarify' type", () => {
+      const result = validateRefineRequest("Some text", "clarify");
+      expect(result).toEqual({ text: "Some text", type: "clarify" });
+    });
+
+    it("accepts valid text and 'add-details' type", () => {
+      const result = validateRefineRequest("Some text", "add-details");
+      expect(result).toEqual({ text: "Some text", type: "add-details" });
+    });
+
+    it("accepts valid text and 'expand' type", () => {
+      const result = validateRefineRequest("Some text", "expand");
+      expect(result).toEqual({ text: "Some text", type: "expand" });
+    });
+
+    it("accepts valid text and 'simplify' type", () => {
+      const result = validateRefineRequest("Some text", "simplify");
+      expect(result).toEqual({ text: "Some text", type: "simplify" });
+    });
+
+    it("throws ValidationError for missing text", () => {
+      expect(() => validateRefineRequest(undefined, "clarify")).toThrow(ValidationError);
+      expect(() => validateRefineRequest(undefined, "clarify")).toThrow("text is required");
+    });
+
+    it("throws ValidationError for null text", () => {
+      expect(() => validateRefineRequest(null, "clarify")).toThrow(ValidationError);
+      expect(() => validateRefineRequest(null, "clarify")).toThrow("text is required");
+    });
+
+    it("throws ValidationError for non-string text", () => {
+      expect(() => validateRefineRequest(123, "clarify")).toThrow(ValidationError);
+      expect(() => validateRefineRequest(123, "clarify")).toThrow("text must be a string");
+    });
+
+    it("throws ValidationError for empty text", () => {
+      expect(() => validateRefineRequest("", "clarify")).toThrow(ValidationError);
+      expect(() => validateRefineRequest("", "clarify")).toThrow(
+        `text must be at least ${MIN_TEXT_LENGTH} character`
+      );
+    });
+
+    it("throws ValidationError for text exceeding MAX_TEXT_LENGTH", () => {
+      const longText = "a".repeat(MAX_TEXT_LENGTH + 1);
+      expect(() => validateRefineRequest(longText, "clarify")).toThrow(ValidationError);
+      expect(() => validateRefineRequest(longText, "clarify")).toThrow(
+        `text must not exceed ${MAX_TEXT_LENGTH} characters`
+      );
+    });
+
+    it("accepts text at exactly MAX_TEXT_LENGTH", () => {
+      const maxText = "a".repeat(MAX_TEXT_LENGTH);
+      const result = validateRefineRequest(maxText, "clarify");
+      expect(result.text).toHaveLength(MAX_TEXT_LENGTH);
+    });
+
+    it("accepts text at exactly MIN_TEXT_LENGTH", () => {
+      const result = validateRefineRequest("a", "clarify");
+      expect(result.text).toBe("a");
+    });
+
+    it("throws ValidationError for missing type", () => {
+      expect(() => validateRefineRequest("some text", undefined)).toThrow(ValidationError);
+      expect(() => validateRefineRequest("some text", undefined)).toThrow("type is required");
+    });
+
+    it("throws ValidationError for null type", () => {
+      expect(() => validateRefineRequest("some text", null)).toThrow(ValidationError);
+      expect(() => validateRefineRequest("some text", null)).toThrow("type is required");
+    });
+
+    it("throws InvalidTypeError for invalid type string", () => {
+      expect(() => validateRefineRequest("some text", "invalid")).toThrow(InvalidTypeError);
+      expect(() => validateRefineRequest("some text", "invalid")).toThrow(
+        "type must be one of: clarify, add-details, expand, simplify"
+      );
+    });
+
+    it("throws InvalidTypeError for numeric type", () => {
+      expect(() => validateRefineRequest("some text", 123)).toThrow(InvalidTypeError);
+    });
+  });
+
+  describe("checkRateLimit", () => {
+    it("allows first request from an IP", () => {
+      expect(checkRateLimit("192.168.1.1")).toBe(true);
+    });
+
+    it("allows up to MAX_REQUESTS_PER_HOUR requests", () => {
+      const ip = "192.168.1.1";
+      for (let i = 0; i < MAX_REQUESTS_PER_HOUR; i++) {
+        expect(checkRateLimit(ip)).toBe(true);
+      }
+    });
+
+    it("blocks request beyond MAX_REQUESTS_PER_HOUR", () => {
+      const ip = "192.168.1.1";
+      // Use up the quota
+      for (let i = 0; i < MAX_REQUESTS_PER_HOUR; i++) {
+        checkRateLimit(ip);
+      }
+      // 11th request should be blocked
+      expect(checkRateLimit(ip)).toBe(false);
+    });
+
+    it("tracks different IPs independently", () => {
+      const ip1 = "192.168.1.1";
+      const ip2 = "192.168.1.2";
+
+      // Use up quota for ip1
+      for (let i = 0; i < MAX_REQUESTS_PER_HOUR; i++) {
+        checkRateLimit(ip1);
+      }
+      expect(checkRateLimit(ip1)).toBe(false);
+
+      // ip2 should still have full quota
+      expect(checkRateLimit(ip2)).toBe(true);
+    });
+
+    it("resets rate limit after RATE_LIMIT_WINDOW_MS", () => {
+      const ip = "192.168.1.1";
+
+      // Use up the quota
+      for (let i = 0; i < MAX_REQUESTS_PER_HOUR; i++) {
+        checkRateLimit(ip);
+      }
+      expect(checkRateLimit(ip)).toBe(false);
+
+      // Advance time by 1 hour + 1ms
+      vi.advanceTimersByTime(RATE_LIMIT_WINDOW_MS + 1);
+
+      // Should be allowed again
+      expect(checkRateLimit(ip)).toBe(true);
+    });
+
+    it("resets count but tracks new window after expiry", () => {
+      const ip = "192.168.1.1";
+
+      // Make 5 requests
+      for (let i = 0; i < 5; i++) {
+        checkRateLimit(ip);
+      }
+
+      // Advance time by 1 hour + 1ms
+      vi.advanceTimersByTime(RATE_LIMIT_WINDOW_MS + 1);
+
+      // First request in new window should work
+      expect(checkRateLimit(ip)).toBe(true);
+
+      // Use up remaining quota in new window
+      for (let i = 0; i < MAX_REQUESTS_PER_HOUR - 1; i++) {
+        expect(checkRateLimit(ip)).toBe(true);
+      }
+
+      // Next request should be blocked
+      expect(checkRateLimit(ip)).toBe(false);
+    });
+  });
+
+  describe("getRateLimitResetTime", () => {
+    it("returns null for unknown IP", () => {
+      expect(getRateLimitResetTime("unknown-ip")).toBeNull();
+    });
+
+    it("returns reset time after a request is made", () => {
+      const ip = "192.168.1.1";
+      const beforeRequest = Date.now();
+
+      checkRateLimit(ip);
+
+      const resetTime = getRateLimitResetTime(ip);
+      expect(resetTime).not.toBeNull();
+      expect(resetTime!.getTime()).toBe(beforeRequest + RATE_LIMIT_WINDOW_MS);
+    });
+
+    it("returns updated reset time after window resets", () => {
+      const ip = "192.168.1.1";
+
+      checkRateLimit(ip);
+      const firstResetTime = getRateLimitResetTime(ip);
+
+      // Advance time past the window
+      vi.advanceTimersByTime(RATE_LIMIT_WINDOW_MS + 1000);
+
+      // Make another request
+      checkRateLimit(ip);
+      const secondResetTime = getRateLimitResetTime(ip);
+
+      // Second reset time should be later than first
+      expect(secondResetTime!.getTime()).toBeGreaterThan(firstResetTime!.getTime());
+    });
+  });
+
+  describe("error classes", () => {
+    it("ValidationError has correct name", () => {
+      const error = new ValidationError("test");
+      expect(error.name).toBe("ValidationError");
+      expect(error.message).toBe("test");
+    });
+
+    it("InvalidTypeError has correct name", () => {
+      const error = new InvalidTypeError("test");
+      expect(error.name).toBe("InvalidTypeError");
+      expect(error.message).toBe("test");
+    });
+
+    it("AiServiceError has correct name", () => {
+      const error = new AiServiceError("test");
+      expect(error.name).toBe("AiServiceError");
+      expect(error.message).toBe("test");
+    });
+  });
+
+  describe("refineText", () => {
+    // Note: refineText requires the AI engine which is not available in tests.
+    // These tests verify error handling when the engine is unavailable.
+
+    it("throws AiServiceError when AI engine is not available", async () => {
+      await expect(refineText("some text", "clarify", "/some/path")).rejects.toThrow(
+        AiServiceError
+      );
+      await expect(refineText("some text", "clarify", "/some/path")).rejects.toThrow(
+        "AI engine not available"
+      );
+    });
+  });
+
+  describe("__resetRefineState", () => {
+    it("clears all rate limit entries", () => {
+      const ip = "192.168.1.1";
+
+      // Make requests to populate rate limits
+      for (let i = 0; i < 5; i++) {
+        checkRateLimit(ip);
+      }
+      expect(getRateLimitResetTime(ip)).not.toBeNull();
+
+      // Reset state
+      __resetRefineState();
+
+      // Should be like starting fresh
+      expect(getRateLimitResetTime(ip)).toBeNull();
+      expect(checkRateLimit(ip)).toBe(true);
+    });
+  });
+});

packages/dashboard/src/ai-refine.ts

@@ -0,0 +1,379 @@
+/**
+ * AI Text Refinement Service
+ *
+ * Provides AI-powered text refinement for task descriptions.
+ * Supports multiple refinement types: clarify, add-details, expand, simplify.
+ *
+ * Features:
+ * - Rate limiting per IP (10 requests per hour)
+ * - Dynamic import of @kb/engine for AI agent creation
+ * - Text length validation (1-2000 characters)
+ */
+
+// Dynamic import for @kb/engine to avoid resolution issues in test environment
+// eslint-disable-next-line @typescript-eslint/consistent-type-imports, @typescript-eslint/no-explicit-any
+type AgentResult = any;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let createKbAgent: any;
+
+// Initialize the import (this runs in actual server, mocked in tests)
+async function initEngine() {
+  if (!createKbAgent) {
+    try {
+      // Use dynamic import with variable to prevent static analysis
+      const engineModule = "@kb/engine";
+      const engine = await import(/* @vite-ignore */ engineModule);
+      createKbAgent = engine.createKbAgent;
+    } catch {
+      // Allow failure in test environments - agent functionality will be stubbed
+      createKbAgent = undefined;
+    }
+  }
+}
+
+// Initialize on module load (will be awaited in actual usage)
+const engineReady = initEngine();
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+/** Available refinement types */
+export type RefinementType = "clarify" | "add-details" | "expand" | "simplify";
+
+/** Valid refinement types for validation */
+export const VALID_REFINEMENT_TYPES: RefinementType[] = [
+  "clarify",
+  "add-details",
+  "expand",
+  "simplify",
+];
+
+/** Request body for text refinement */
+export interface RefineTextRequest {
+  text: string;
+  type: RefinementType;
+}
+
+/** Response body for text refinement */
+export interface RefineTextResponse {
+  refined: string;
+}
+
+// ── Constants ───────────────────────────────────────────────────────────────
+
+/** System prompt for text refinement */
+export const REFINE_SYSTEM_PROMPT = `You are a text refinement assistant for a task management system.
+
+Your job is to refine task descriptions based on the user's selected refinement type.
+
+## Refinement Types
+
+1. **clarify**: Make the description clearer and more specific
+   - Remove ambiguity
+   - Add specific details where vague
+   - Ensure the goal is well-defined
+   - Keep approximately the same length
+
+2. **add-details**: Add implementation details and context
+   - Add technical considerations
+   - Include edge cases to consider
+   - Mention related files/components if apparent
+   - Expand moderately (1.5-2x length)
+
+3. **expand**: Expand into a more comprehensive description
+   - Add background context
+   - Include acceptance criteria
+   - List specific sub-tasks or steps
+   - Significantly expand (2-3x length)
+
+4. **simplify**: Simplify and make more concise
+   - Remove redundant words
+   - Use concise language
+   - Keep core meaning intact
+   - Reduce length significantly (0.5-0.7x)
+
+## Guidelines
+- Maintain the original intent and meaning
+- Keep the tone professional and actionable
+- Output ONLY the refined text, no markdown formatting, no explanations
+- The output should be a direct replacement for the input text`;
+
+/** Maximum text length in characters */
+export const MAX_TEXT_LENGTH = 2000;
+
+/** Minimum text length in characters */
+export const MIN_TEXT_LENGTH = 1;
+
+/** Rate limit: max requests per IP per hour */
+export const MAX_REQUESTS_PER_HOUR = 10;
+
+/** Rate limit window in milliseconds (1 hour) */
+export const RATE_LIMIT_WINDOW_MS = 60 * 60 * 1000;
+
+/** Cleanup interval in milliseconds (5 minutes) */
+export const CLEANUP_INTERVAL_MS = 5 * 60 * 1000;
+
+// ── Rate Limiting ─────────────────────────────────────────────────────────
+
+interface RateLimitEntry {
+  count: number;
+  firstRequestAt: Date;
+}
+
+/** Rate limiting state indexed by IP */
+const rateLimits = new Map<string, RateLimitEntry>();
+
+/**
+ * Check if IP can make a refinement request.
+ * Returns true if allowed, false if rate limited.
+ */
+export function checkRateLimit(ip: string): boolean {
+  const now = Date.now();
+  const entry = rateLimits.get(ip);
+
+  if (!entry) {
+    // First request from this IP
+    rateLimits.set(ip, {
+      count: 1,
+      firstRequestAt: new Date(),
+    });
+    return true;
+  }
+
+  // Check if window has expired
+  if (now - entry.firstRequestAt.getTime() > RATE_LIMIT_WINDOW_MS) {
+    // Reset window
+    rateLimits.set(ip, {
+      count: 1,
+      firstRequestAt: new Date(),
+    });
+    return true;
+  }
+
+  // Within window - check limit
+  if (entry.count >= MAX_REQUESTS_PER_HOUR) {
+    return false;
+  }
+
+  // Increment count
+  entry.count++;
+  return true;
+}
+
+/**
+ * Get rate limit reset time for an IP.
+ * Returns null if no rate limit entry exists.
+ */
+export function getRateLimitResetTime(ip: string): Date | null {
+  const entry = rateLimits.get(ip);
+  if (!entry) return null;
+
+  return new Date(entry.firstRequestAt.getTime() + RATE_LIMIT_WINDOW_MS);
+}
+
+/**
+ * Remove expired rate limit entries.
+ * Runs periodically via setInterval.
+ */
+function cleanupExpiredRateLimits(): void {
+  const now = Date.now();
+  let cleanedRateLimits = 0;
+
+  for (const [ip, entry] of rateLimits) {
+    if (now - entry.firstRequestAt.getTime() > RATE_LIMIT_WINDOW_MS) {
+      rateLimits.delete(ip);
+      cleanedRateLimits++;
+    }
+  }
+
+  if (cleanedRateLimits > 0) {
+    console.log(`[ai-refine] Cleanup: removed ${cleanedRateLimits} rate limit entries`);
+  }
+}
+
+// Start cleanup interval
+const cleanupInterval = setInterval(cleanupExpiredRateLimits, CLEANUP_INTERVAL_MS);
+
+// Handle graceful shutdown
+process.on("beforeExit", () => {
+  clearInterval(cleanupInterval);
+});
+
+// ── Validation ──────────────────────────────────────────────────────────────
+
+/**
+ * Validate refinement request.
+ * Throws appropriate errors for invalid input.
+ */
+export function validateRefineRequest(
+  text: unknown,
+  type: unknown
+): { text: string; type: RefinementType } {
+  // Validate text exists
+  if (text === undefined || text === null) {
+    throw new ValidationError("text is required");
+  }
+
+  // Validate text is a string
+  if (typeof text !== "string") {
+    throw new ValidationError("text must be a string");
+  }
+
+  // Validate text length
+  if (text.length < MIN_TEXT_LENGTH) {
+    throw new ValidationError(
+      `text must be at least ${MIN_TEXT_LENGTH} character${MIN_TEXT_LENGTH === 1 ? "" : "s"}`
+    );
+  }
+  if (text.length > MAX_TEXT_LENGTH) {
+    throw new ValidationError(
+      `text must not exceed ${MAX_TEXT_LENGTH} characters`
+    );
+  }
+
+  // Validate type exists
+  if (type === undefined || type === null) {
+    throw new ValidationError("type is required");
+  }
+
+  // Validate type is a valid refinement type
+  if (!VALID_REFINEMENT_TYPES.includes(type as RefinementType)) {
+    throw new InvalidTypeError(
+      `type must be one of: ${VALID_REFINEMENT_TYPES.join(", ")}`
+    );
+  }
+
+  return { text, type: type as RefinementType };
+}
+
+// ── AI Integration ───────────────────────────────────────────────────────────
+
+/**
+ * Refine text using AI agent.
+ * @param text - The text to refine
+ * @param type - The type of refinement to apply
+ * @param rootDir - Project root directory for AI agent context
+ * @returns The refined text
+ */
+export async function refineText(
+  text: string,
+  type: RefinementType,
+  rootDir: string
+): Promise<string> {
+  // Ensure engine is loaded before using createKbAgent
+  await engineReady;
+
+  if (!createKbAgent) {
+    throw new AiServiceError("AI engine not available");
+  }
+
+  const agentResult = await createKbAgent({
+    cwd: rootDir,
+    systemPrompt: REFINE_SYSTEM_PROMPT,
+    tools: "readonly",
+  });
+
+  if (!agentResult?.session) {
+    throw new AiServiceError("Failed to initialize AI agent");
+  }
+
+  // Build the prompt with type instruction
+  const prompt = `Refinement type: ${type}\n\nText to refine:\n${text}`;
+
+  try {
+    // Send message to agent and get response
+    await agentResult.session.prompt(prompt);
+
+    // Get the response text from the agent's state
+    interface AgentMessage {
+      role: string;
+      content?: string | Array<{ type: string; text: string }>;
+    }
+    const lastMessage = (agentResult.session.state.messages as AgentMessage[])
+      .filter((m: AgentMessage) => m.role === "assistant")
+      .pop();
+
+    let refinedText = "";
+    if (lastMessage?.content) {
+      // Handle both string and array content types
+      if (typeof lastMessage.content === "string") {
+        refinedText = lastMessage.content.trim();
+      } else if (Array.isArray(lastMessage.content)) {
+        // Extract text from content blocks
+        refinedText = lastMessage.content
+          .filter((c: { type: string; text: string }): c is { type: "text"; text: string } => c.type === "text")
+          .map((c: { type: string; text: string }) => c.text)
+          .join("")
+          .trim();
+      }
+    }
+
+    if (!refinedText) {
+      throw new AiServiceError("AI returned empty response");
+    }
+
+    // Dispose the agent session
+    try {
+      agentResult.session.dispose?.();
+    } catch {
+      // Ignore disposal errors
+    }
+
+    return refinedText;
+  } catch (err) {
+    // Ensure session is disposed even on error
+    try {
+      agentResult.session.dispose?.();
+    } catch {
+      // Ignore disposal errors
+    }
+
+    if (err instanceof AiServiceError) {
+      throw err;
+    }
+    throw new AiServiceError(
+      err instanceof Error ? err.message : "AI processing failed"
+    );
+  }
+}
+
+// ── Custom Errors ───────────────────────────────────────────────────────────
+
+export class ValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ValidationError";
+  }
+}
+
+export class InvalidTypeError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InvalidTypeError";
+  }
+}
+
+export class RateLimitError extends Error {
+  resetTime: Date | null;
+
+  constructor(message: string, resetTime: Date | null = null) {
+    super(message);
+    this.name = "RateLimitError";
+    this.resetTime = resetTime;
+  }
+}
+
+export class AiServiceError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "AiServiceError";
+  }
+}
+
+// ── Test Helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Reset all refinement state. Used for testing only.
+ */
+export function __resetRefineState(): void {
+  rateLimits.clear();
+}

packages/dashboard/src/routes.ts

@@ -3800,6 +3800,72 @@ export function createApiRoutes(store: TaskStore, options?: ServerOptions): Rout
     }
   });
 
+  /**
+   * POST /api/ai/refine-text
+   * AI-powered text refinement for task descriptions.
+   * Body: { text: string, type: string }
+   * Returns: { refined: string }
+   *
+   * Refinement types: clarify, add-details, expand, simplify
+   * Rate limited: 10 requests per hour per IP
+   */
+  router.post("/ai/refine-text", async (req, res) => {
+    try {
+      const { text, type } = req.body;
+      const ip = req.ip || req.socket.remoteAddress || "unknown";
+      const rootDir = store.getRootDir();
+
+      const {
+        validateRefineRequest,
+        checkRateLimit,
+        getRateLimitResetTime,
+        refineText,
+        RateLimitError,
+        ValidationError,
+        InvalidTypeError,
+        AiServiceError,
+      } = await import("./ai-refine.js");
+
+      // Check rate limit first
+      if (!checkRateLimit(ip)) {
+        const resetTime = getRateLimitResetTime(ip);
+        res.status(429).json({
+          error: `Rate limit exceeded. Maximum 10 refinement requests per hour. Reset at ${resetTime?.toISOString() || "unknown"}`,
+        });
+        return;
+      }
+
+      // Validate request body
+      let validated;
+      try {
+        validated = validateRefineRequest(text, type);
+      } catch (err) {
+        if (err instanceof ValidationError) {
+          res.status(400).json({ error: err.message });
+          return;
+        }
+        if (err instanceof InvalidTypeError) {
+          res.status(422).json({ error: err.message });
+          return;
+        }
+        throw err;
+      }
+
+      // Process refinement
+      const refined = await refineText(validated.text, validated.type, rootDir);
+      res.json({ refined });
+    } catch (err: any) {
+      // Check error by name since error classes are from dynamic import
+      if (err?.name === "RateLimitError") {
+        res.status(429).json({ error: err.message });
+      } else if (err?.name === "AiServiceError") {
+        res.status(500).json({ error: err.message || "AI service error" });
+      } else {
+        res.status(500).json({ error: err?.message || "Failed to refine text" });
+      }
+    }
+  });
+
   /**
    * GET /api/usage
    * Fetch AI provider subscription usage (Claude, Codex, Gemini).