Refactor settings schema with Zod validation and add readSettings tests (#2676)

src/__tests__/readSettings.test.ts

@@ -310,6 +310,85 @@ describe("readSettings", () => {
       );
     });
 
+    it("should migrate deprecated 'agent' chat mode to 'build'", () => {
+      const mockFileContent = {
+        selectedModel: {
+          name: "gpt-4",
+          provider: "openai",
+        },
+        selectedChatMode: "agent",
+        defaultChatMode: "agent",
+      };
+
+      mockFs.existsSync.mockReturnValue(true);
+      mockFs.readFileSync.mockReturnValue(JSON.stringify(mockFileContent));
+
+      const result = readSettings();
+
+      // "agent" should be migrated to "build"
+      expect(result.selectedChatMode).toBe("build");
+      expect(result.defaultChatMode).toBe("build");
+    });
+
+    it("should preserve non-deprecated chat modes", () => {
+      const mockFileContent = {
+        selectedModel: {
+          name: "gpt-4",
+          provider: "openai",
+        },
+        selectedChatMode: "local-agent",
+        defaultChatMode: "ask",
+      };
+
+      mockFs.existsSync.mockReturnValue(true);
+      mockFs.readFileSync.mockReturnValue(JSON.stringify(mockFileContent));
+
+      const result = readSettings();
+
+      expect(result.selectedChatMode).toBe("local-agent");
+      expect(result.defaultChatMode).toBe("ask");
+    });
+
+    it("should migrate deprecated 'agent' chat mode to 'build'", () => {
+      const mockFileContent = {
+        selectedModel: {
+          name: "gpt-4",
+          provider: "openai",
+        },
+        selectedChatMode: "agent",
+        defaultChatMode: "agent",
+      };
+
+      mockFs.existsSync.mockReturnValue(true);
+      mockFs.readFileSync.mockReturnValue(JSON.stringify(mockFileContent));
+
+      const result = readSettings();
+
+      // "agent" should be converted to "build" on read
+      expect(result.selectedChatMode).toBe("build");
+      expect(result.defaultChatMode).toBe("build");
+    });
+
+    it("should preserve non-deprecated chat modes during migration", () => {
+      const mockFileContent = {
+        selectedModel: {
+          name: "gpt-4",
+          provider: "openai",
+        },
+        selectedChatMode: "local-agent",
+        defaultChatMode: "ask",
+      };
+
+      mockFs.existsSync.mockReturnValue(true);
+      mockFs.readFileSync.mockReturnValue(JSON.stringify(mockFileContent));
+
+      const result = readSettings();
+
+      // non-deprecated modes should be preserved
+      expect(result.selectedChatMode).toBe("local-agent");
+      expect(result.defaultChatMode).toBe("ask");
+    });
+
     it("should preserve extra fields not recognized by the schema", () => {
       const mockFileContent = {
         selectedModel: {

src/components/ChatInputControls.tsx

@@ -17,12 +17,11 @@ export function ChatInputControls({
 
   // Show MCP tools picker when:
   // 1. The enableMcpServersForBuildMode experiment is on AND
-  // 2. Mode is "agent" (backwards compatibility) OR
-  //    mode is "build" AND there are enabled MCP servers
+  // 2. Mode is "build" AND there are enabled MCP servers
   const showMcpToolsPicker =
     !!settings?.enableMcpServersForBuildMode &&
-    (settings?.selectedChatMode === "agent" ||
-      (settings?.selectedChatMode === "build" && enabledMcpServersCount > 0));
+    settings?.selectedChatMode === "build" &&
+    enabledMcpServersCount > 0;
 
   return (
     <div className="flex items-center">

src/components/ChatModeSelector.tsx

@@ -40,9 +40,8 @@ export function ChatModeSelector() {
   const chatId = routerState.location.search.id as number | undefined;
   const currentChatMessages = chatId ? (messagesById.get(chatId) ?? []) : [];
 
-  // Treat "agent" mode as "build" for UI purposes (backwards compatibility)
-  const rawSelectedMode = settings?.selectedChatMode || "build";
-  const selectedMode = rawSelectedMode === "agent" ? "build" : rawSelectedMode;
+  // Migration happens on read, so selectedChatMode will never be "agent"
+  const selectedMode = settings?.selectedChatMode || "build";
   const isProEnabled = settings ? isDyadProEnabled(settings) : false;
   const { messagesRemaining, isQuotaExceeded } = useFreeAgentQuota();
   const { servers } = useMcp();
@@ -83,7 +82,6 @@ export function ChatModeSelector() {
   const getModeDisplayName = (mode: ChatMode) => {
     switch (mode) {
       case "build":
-      case "agent": // backwards compatibility - treat as build
         return "Build";
       case "ask":
         return "Ask";
@@ -100,7 +98,6 @@ export function ChatModeSelector() {
   const getModeIcon = (mode: ChatMode) => {
     switch (mode) {
       case "build":
-      case "agent":
         return <Hammer size={14} />;
       case "ask":
         return <MessageCircle size={14} />;

src/components/DefaultChatModeSelector.tsx

@@ -38,11 +38,13 @@ export function DefaultChatModeSelector() {
   const getModeDisplayName = (mode: ChatMode) => {
     switch (mode) {
       case "build":
-      case "agent": // backwards compatibility - treat as build
         return "Build";
       case "local-agent":
         return isProEnabled ? "Agent" : "Basic Agent";
       case "ask":
+        return "Ask";
+      case "plan":
+        return "Plan";
       default:
         throw new Error(`Unknown chat mode: ${mode}`);
     }

src/hooks/useChatModeToggle.ts

@@ -20,17 +20,14 @@ export function useChatModeToggle() {
     [isMac],
   );
 
-  // Function to toggle between chat modes (skipping deprecated "agent" mode)
+  // Function to toggle between chat modes
   const toggleChatMode = useCallback(() => {
     if (!settings || !settings.selectedChatMode) return;
 
     const currentMode = settings.selectedChatMode;
-    // Filter out deprecated "agent" mode from toggle cycle
-    const modes = ChatModeSchema.options.filter((m) => m !== "agent");
-    // If current mode is "agent", treat it as "build" for indexing
-    const effectiveCurrentMode =
-      currentMode === "agent" ? "build" : currentMode;
-    const currentIndex = modes.indexOf(effectiveCurrentMode);
+    // Migration on read ensures currentMode is never "agent"
+    const modes = ChatModeSchema.options;
+    const currentIndex = modes.indexOf(currentMode);
     const newMode = modes[(currentIndex + 1) % modes.length];
 
     updateSettings({ selectedChatMode: newMode });

src/ipc/handlers/chat_stream_handlers.ts

@@ -683,12 +683,10 @@ ${componentSnippet}
           `Theme for app ${updatedChat.app.id}: ${updatedChat.app.themeId ?? "none"}, prompt length: ${themePrompt.length} chars`,
         );
 
+        // Migration on read converts "agent" to "build", so no need to check for it here
         let systemPrompt = constructSystemPrompt({
           aiRules,
-          chatMode:
-            settings.selectedChatMode === "agent"
-              ? "build"
-              : settings.selectedChatMode,
+          chatMode: settings.selectedChatMode,
           enableTurboEditsV2: isTurboEditsV2Enabled(settings),
           themePrompt,
           basicAgentMode: isBasicAgentMode(settings),
@@ -1204,18 +1202,16 @@ This conversation includes one or more image attachments. When the user uploads
 
         // Use MCP agent code path if:
         // 1. The enableMcpServersForBuildMode experiment is on AND
-        // 2. Mode is explicitly "agent" (backwards compatibility for existing settings)
-        //    OR mode is "build" AND there are enabled MCP servers
+        // 2. Mode is "build" AND there are enabled MCP servers
         if (
           settings.enableMcpServersForBuildMode &&
-          (settings.selectedChatMode === "agent" ||
-            settings.selectedChatMode === "build")
+          settings.selectedChatMode === "build"
         ) {
           const tools = await getMcpTools(event);
           const hasEnabledMcpServers = Object.keys(tools).length > 0;
 
-          // Only run MCP agent path if mode is "agent" OR if build mode has enabled MCP servers
-          if (settings.selectedChatMode === "agent" || hasEnabledMcpServers) {
+          // Only run MCP agent path if build mode has enabled MCP servers
+          if (hasEnabledMcpServers) {
             const { fullStream } = await simpleStreamText({
               chatMessages: limitedHistoryChatMessages,
               modelClient,
@@ -1232,7 +1228,7 @@ This conversation includes one or more image attachments. When the user uploads
                 aiRules: await readAiRules(
                   getDyadAppPath(updatedChat.app.path),
                 ),
-                chatMode: "agent",
+                chatMode: "build",
                 enableTurboEditsV2: false,
               }),
               files: files,

src/ipc/handlers/token_count_handlers.ts

@@ -64,11 +64,11 @@ export function registerTokenCountHandlers() {
       const mentionedAppNames = parseAppMentions(req.input);
 
       // Count system prompt tokens
+      // Migration on read converts "agent" to "build", so no need to check for it here
       const themePrompt = await getThemePromptById(chat.app?.themeId ?? null);
       let systemPrompt = constructSystemPrompt({
         aiRules: await readAiRules(getDyadAppPath(chat.app.path)),
         chatMode:
-          settings.selectedChatMode === "agent" ||
           settings.selectedChatMode === "local-agent"
             ? "build"
             : settings.selectedChatMode,

src/lib/schemas.ts

@@ -143,13 +143,22 @@ export type RuntimeMode = z.infer<typeof RuntimeModeSchema>;
 export const RuntimeMode2Schema = z.enum(["host", "docker"]);
 export type RuntimeMode2 = z.infer<typeof RuntimeMode2Schema>;
 
-export const ChatModeSchema = z.enum([
+/**
+ * Chat modes that can be stored in settings (includes deprecated values for backwards compat)
+ */
+export const StoredChatModeSchema = z.enum([
   "build",
   "ask",
-  "agent",
+  "agent", // DEPRECATED: converted to "build" on read
   "local-agent",
   "plan",
 ]);
+export type StoredChatMode = z.infer<typeof StoredChatModeSchema>;
+
+/**
+ * Active chat modes (excludes deprecated values)
+ */
+export const ChatModeSchema = z.enum(["build", "ask", "local-agent", "plan"]);
 export type ChatMode = z.infer<typeof ChatModeSchema>;
 
 export const GitHubSecretsSchema = z.object({
@@ -270,80 +279,109 @@ export const AgentToolConsentSchema = z.enum(["ask", "always", "never"]);
 export type AgentToolConsent = z.infer<typeof AgentToolConsentSchema>;
 
 /**
- * Zod schema for user settings
+ * Base fields shared between StoredUserSettings and UserSettings
+ */
+const BaseUserSettingsFields = {
+  ////////////////////////////////
+  // E2E TESTING ONLY.
+  ////////////////////////////////
+  isTestMode: z.boolean().optional(),
+
+  ////////////////////////////////
+  // DEPRECATED.
+  ////////////////////////////////
+  enableProSaverMode: z.boolean().optional(),
+  dyadProBudget: DyadProBudgetSchema.optional(),
+  runtimeMode: RuntimeModeSchema.optional(),
+
+  ////////////////////////////////
+  // ACTIVE FIELDS.
+  ////////////////////////////////
+  selectedModel: LargeLanguageModelSchema,
+  providerSettings: z.record(z.string(), ProviderSettingSchema),
+  agentToolConsents: z.record(z.string(), AgentToolConsentSchema).optional(),
+  githubUser: GithubUserSchema.optional(),
+  githubAccessToken: SecretSchema.optional(),
+  vercelAccessToken: SecretSchema.optional(),
+  supabase: SupabaseSchema.optional(),
+  neon: NeonSchema.optional(),
+  autoApproveChanges: z.boolean().optional(),
+  telemetryConsent: z.enum(["opted_in", "opted_out", "unset"]).optional(),
+  telemetryUserId: z.string().optional(),
+  hasRunBefore: z.boolean().optional(),
+  enableDyadPro: z.boolean().optional(),
+  experiments: ExperimentsSchema.optional(),
+  lastShownReleaseNotesVersion: z.string().optional(),
+  maxChatTurnsInContext: z.number().optional(),
+  thinkingBudget: z.enum(["low", "medium", "high"]).optional(),
+  enableProLazyEditsMode: z.boolean().optional(),
+  proLazyEditsMode: z.enum(["off", "v1", "v2"]).optional(),
+  enableProSmartFilesContextMode: z.boolean().optional(),
+  enableProWebSearch: z.boolean().optional(),
+  proSmartContextOption: SmartContextModeSchema.optional(),
+  selectedTemplateId: z.string(),
+  selectedThemeId: z.string().optional(),
+  enableSupabaseWriteSqlMigration: z.boolean().optional(),
+  skipPruneEdgeFunctions: z.boolean().optional(),
+  acceptedCommunityCode: z.boolean().optional(),
+  zoomLevel: ZoomLevelSchema.optional(),
+  language: LanguageSchema.optional(),
+  previewDeviceMode: DeviceModeSchema.optional(),
+
+  enableAutoFixProblems: z.boolean().optional(),
+  autoExpandPreviewPanel: z.boolean().optional(),
+  enableChatCompletionNotifications: z.boolean().optional(),
+  enableNativeGit: z.boolean().optional(),
+  enableMcpServersForBuildMode: z.boolean().optional(),
+  enableAutoUpdate: z.boolean(),
+  releaseChannel: ReleaseChannelSchema,
+  runtimeMode2: RuntimeMode2Schema.optional(),
+  customNodePath: z.string().optional().nullable(),
+  isRunning: z.boolean().optional(),
+  lastKnownPerformance: z
+    .object({
+      timestamp: z.number(),
+      memoryUsageMB: z.number(),
+      cpuUsagePercent: z.number().optional(),
+      systemMemoryUsageMB: z.number().optional(),
+      systemMemoryTotalMB: z.number().optional(),
+      systemCpuPercent: z.number().optional(),
+    })
+    .optional(),
+  hideLocalAgentNewChatToast: z.boolean().optional(),
+  enableContextCompaction: z.boolean().optional(),
+};
+
+/**
+ * Zod schema for stored user settings (includes deprecated values for backwards compat).
+ * This is what gets written to/read from the JSON file.
+ */
+export const StoredUserSettingsSchema = z
+  .object({
+    ...BaseUserSettingsFields,
+    // Use StoredChatModeSchema to allow deprecated "agent" value
+    selectedChatMode: StoredChatModeSchema.optional(),
+    defaultChatMode: StoredChatModeSchema.optional(),
+  })
+  // Allow unknown properties to pass through (e.g. future settings
+  // that should be preserved if user downgrades to an older version)
+  .passthrough();
+
+/**
+ * Type derived from the StoredUserSettingsSchema
+ */
+export type StoredUserSettings = z.infer<typeof StoredUserSettingsSchema>;
+
+/**
+ * Zod schema for active user settings (excludes deprecated values).
+ * This is what the application uses at runtime.
  */
 export const UserSettingsSchema = z
   .object({
-    ////////////////////////////////
-    // E2E TESTING ONLY.
-    ////////////////////////////////
-    isTestMode: z.boolean().optional(),
-
-    ////////////////////////////////
-    // DEPRECATED.
-    ////////////////////////////////
-    enableProSaverMode: z.boolean().optional(),
-    dyadProBudget: DyadProBudgetSchema.optional(),
-    runtimeMode: RuntimeModeSchema.optional(),
-
-    ////////////////////////////////
-    // ACTIVE FIELDS.
-    ////////////////////////////////
-    selectedModel: LargeLanguageModelSchema,
-    providerSettings: z.record(z.string(), ProviderSettingSchema),
-    agentToolConsents: z.record(z.string(), AgentToolConsentSchema).optional(),
-    githubUser: GithubUserSchema.optional(),
-    githubAccessToken: SecretSchema.optional(),
-    vercelAccessToken: SecretSchema.optional(),
-    supabase: SupabaseSchema.optional(),
-    neon: NeonSchema.optional(),
-    autoApproveChanges: z.boolean().optional(),
-    telemetryConsent: z.enum(["opted_in", "opted_out", "unset"]).optional(),
-    telemetryUserId: z.string().optional(),
-    hasRunBefore: z.boolean().optional(),
-    enableDyadPro: z.boolean().optional(),
-    experiments: ExperimentsSchema.optional(),
-    lastShownReleaseNotesVersion: z.string().optional(),
-    maxChatTurnsInContext: z.number().optional(),
-    thinkingBudget: z.enum(["low", "medium", "high"]).optional(),
-    enableProLazyEditsMode: z.boolean().optional(),
-    proLazyEditsMode: z.enum(["off", "v1", "v2"]).optional(),
-    enableProSmartFilesContextMode: z.boolean().optional(),
-    enableProWebSearch: z.boolean().optional(),
-    proSmartContextOption: SmartContextModeSchema.optional(),
-    selectedTemplateId: z.string(),
-    selectedThemeId: z.string().optional(),
-    enableSupabaseWriteSqlMigration: z.boolean().optional(),
-    skipPruneEdgeFunctions: z.boolean().optional(),
+    ...BaseUserSettingsFields,
+    // Use ChatModeSchema which excludes deprecated "agent" value
     selectedChatMode: ChatModeSchema.optional(),
     defaultChatMode: ChatModeSchema.optional(),
-    acceptedCommunityCode: z.boolean().optional(),
-    zoomLevel: ZoomLevelSchema.optional(),
-    language: LanguageSchema.optional(),
-    previewDeviceMode: DeviceModeSchema.optional(),
-
-    enableAutoFixProblems: z.boolean().optional(),
-    autoExpandPreviewPanel: z.boolean().optional(),
-    enableChatCompletionNotifications: z.boolean().optional(),
-    enableNativeGit: z.boolean().optional(),
-    enableMcpServersForBuildMode: z.boolean().optional(),
-    enableAutoUpdate: z.boolean(),
-    releaseChannel: ReleaseChannelSchema,
-    runtimeMode2: RuntimeMode2Schema.optional(),
-    customNodePath: z.string().optional().nullable(),
-    isRunning: z.boolean().optional(),
-    lastKnownPerformance: z
-      .object({
-        timestamp: z.number(),
-        memoryUsageMB: z.number(),
-        cpuUsagePercent: z.number().optional(),
-        systemMemoryUsageMB: z.number().optional(),
-        systemMemoryTotalMB: z.number().optional(),
-        systemCpuPercent: z.number().optional(),
-      })
-      .optional(),
-    hideLocalAgentNewChatToast: z.boolean().optional(),
-    enableContextCompaction: z.boolean().optional(),
   })
   // Allow unknown properties to pass through (e.g. future settings
   // that should be preserved if user downgrades to an older version)
@@ -354,6 +392,33 @@ export const UserSettingsSchema = z
  */
 export type UserSettings = z.infer<typeof UserSettingsSchema>;
 
+/**
+ * Migrates a stored chat mode to an active chat mode.
+ * Converts deprecated "agent" mode to "build".
+ */
+export function migrateStoredChatMode(
+  mode: StoredChatMode | undefined,
+): ChatMode | undefined {
+  if (mode === "agent") {
+    return "build";
+  }
+  return mode;
+}
+
+/**
+ * Migrates stored settings to active settings.
+ * Applies necessary transformations for deprecated values.
+ */
+export function migrateStoredSettings(
+  stored: StoredUserSettings,
+): UserSettings {
+  return {
+    ...stored,
+    selectedChatMode: migrateStoredChatMode(stored.selectedChatMode),
+    defaultChatMode: migrateStoredChatMode(stored.defaultChatMode),
+  };
+}
+
 export function isDyadProEnabled(settings: UserSettings): boolean {
   return settings.enableDyadPro === true && hasDyadProKey(settings);
 }

src/main/settings.ts

@@ -2,10 +2,12 @@ import fs from "node:fs";
 import path from "node:path";
 import { getUserDataPath } from "../paths/paths";
 import {
+  StoredUserSettingsSchema,
   UserSettingsSchema,
   type UserSettings,
   Secret,
   VertexProviderSetting,
+  migrateStoredSettings,
 } from "../lib/schemas";
 import { safeStorage } from "electron";
 import { v4 as uuidv4 } from "uuid";
@@ -165,13 +167,16 @@ export function readSettings(): UserSettings {
       }
     }
 
-    // Validate and merge with defaults
-    const validatedSettings = UserSettingsSchema.parse(combinedSettings);
+    // Validate stored settings (allows deprecated values like "agent" chat mode)
+    const storedSettings = StoredUserSettingsSchema.parse(combinedSettings);
     // "conservative" is deprecated, use undefined to use the default value
-    if (validatedSettings.proSmartContextOption === "conservative") {
-      validatedSettings.proSmartContextOption = undefined;
+    if (storedSettings.proSmartContextOption === "conservative") {
+      storedSettings.proSmartContextOption = undefined;
     }
-    return validatedSettings;
+    // Migrate stored settings to active settings (converts deprecated values)
+    const migratedSettings = migrateStoredSettings(storedSettings);
+    // Validate the migrated settings against the active schema
+    return UserSettingsSchema.parse(migratedSettings);
   } catch (error) {
     logger.error("Error reading settings:", error);
     return DEFAULT_SETTINGS;
@@ -242,7 +247,8 @@ export function writeSettings(settings: Partial<UserSettings>): void {
         v.serviceAccountKey = encrypt(v.serviceAccountKey.value);
       }
     }
-    const validatedSettings = UserSettingsSchema.parse(newSettings);
+    // Use StoredUserSettingsSchema for writing to maintain backwards compatibility
+    const validatedSettings = StoredUserSettingsSchema.parse(newSettings);
     fs.writeFileSync(filePath, JSON.stringify(validatedSettings, null, 2));
   } catch (error) {
     logger.error("Error writing settings:", error);

src/prompts/system_prompt.ts

@@ -453,7 +453,9 @@ IF YOU USE ANY OF THESE TAGS, YOU WILL BE FIRED.
 
 Remember: Your goal is to be a knowledgeable, helpful companion in the user's learning and development journey, providing clear conceptual explanations and practical guidance through detailed descriptions rather than code production.`;
 
-const AGENT_MODE_SYSTEM_PROMPT = `
+// Deprecated: This prompt was for the legacy "agent" chat mode which has been removed.
+// Keeping for reference but prefixed with _ to indicate it's intentionally unused.
+const _AGENT_MODE_SYSTEM_PROMPT = `
 You are an AI App Builder Agent. Your role is to analyze app development requests and gather all necessary information before the actual coding phase begins.
 
 ## Core Mission
@@ -514,7 +516,7 @@ export const constructSystemPrompt = ({
   basicAgentMode,
 }: {
   aiRules: string | undefined;
-  chatMode?: "build" | "ask" | "agent" | "local-agent" | "plan";
+  chatMode?: "build" | "ask" | "local-agent" | "plan";
   enableTurboEditsV2: boolean;
   themePrompt?: string;
   /** If true, use read-only mode for local-agent (ask mode with tools) */
@@ -554,12 +556,9 @@ export const getSystemPromptForChatMode = ({
   chatMode,
   enableTurboEditsV2,
 }: {
-  chatMode: "build" | "ask" | "agent";
+  chatMode: "build" | "ask";
   enableTurboEditsV2: boolean;
 }) => {
-  if (chatMode === "agent") {
-    return AGENT_MODE_SYSTEM_PROMPT;
-  }
   if (chatMode === "ask") {
     return ASK_MODE_SYSTEM_PROMPT;
   }