Merge pull request #251 from cloudflare/feat/proper-finalization

AshishKumar4 · web-flow · commit 38b0e8a2f407 · 2025-11-22T16:21:20.000-05:00
Refactor: improve static analysis caching and finalization phase generation rewrite
diff --git a/worker/agents/core/simpleGeneratorAgent.ts b/worker/agents/core/simpleGeneratorAgent.ts
@@ -95,6 +95,8 @@ export class SimpleCodeGeneratorAgent extends Agent<Env, CodeGenState> {
     private currentAbortController?: AbortController;
     private deepDebugPromise: Promise<{ transcript: string } | { error: string }> | null = null;
     private deepDebugConversationId: string | null = null;
+
+    private staticAnalysisCache: StaticAnalysisResponse | null = null;
     
     // GitHub token cache (ephemeral, lost on DO eviction)
     private githubTokenCache: {
@@ -858,7 +860,6 @@ export class SimpleCodeGeneratorAgent extends Agent<Env, CodeGenState> {
             this.createNewIncompletePhase(phaseConcept);
         }
 
-        let staticAnalysisCache: StaticAnalysisResponse | undefined;
         let userContext: UserContext | undefined;
 
         // Store review cycles for later use
@@ -877,13 +878,11 @@ export class SimpleCodeGeneratorAgent extends Agent<Env, CodeGenState> {
                         executionResults = await this.executePhaseGeneration();
                         currentDevState = executionResults.currentDevState;
                         phaseConcept = executionResults.result;
-                        staticAnalysisCache = executionResults.staticAnalysis;
                         userContext = executionResults.userContext;
                         break;
                     case CurrentDevState.PHASE_IMPLEMENTING:
-                        executionResults = await this.executePhaseImplementation(phaseConcept, staticAnalysisCache, userContext);
+                        executionResults = await this.executePhaseImplementation(phaseConcept, userContext);
                         currentDevState = executionResults.currentDevState;
-                        staticAnalysisCache = executionResults.staticAnalysis;
                         userContext = undefined;
                         break;
                     case CurrentDevState.REVIEWING:
@@ -923,11 +922,11 @@ export class SimpleCodeGeneratorAgent extends Agent<Env, CodeGenState> {
             });
         }
     }
-
+    
     /**
      * Execute phase generation state - generate next phase with user suggestions
      */
-    async executePhaseGeneration(): Promise<PhaseExecutionResult> {
+    async executePhaseGeneration(isFinal?: boolean): Promise<PhaseExecutionResult> {
         this.logger().info("Executing PHASE_GENERATING state");
         try {
             const currentIssues = await this.fetchAllIssues();
@@ -958,7 +957,7 @@ export class SimpleCodeGeneratorAgent extends Agent<Env, CodeGenState> {
                 }
             }
             
-            const nextPhase = await this.generateNextPhase(currentIssues, userContext);
+            const nextPhase = await this.generateNextPhase(currentIssues, userContext, isFinal);
                 
             if (!nextPhase) {
                 this.logger().info("No more phases to implement, transitioning to FINALIZING");
@@ -976,7 +975,6 @@ export class SimpleCodeGeneratorAgent extends Agent<Env, CodeGenState> {
             return {
                 currentDevState: CurrentDevState.PHASE_IMPLEMENTING,
                 result: nextPhase,
-                staticAnalysis: currentIssues.staticAnalysis,
                 userContext: userContext,
             };
         } catch (error) {
@@ -993,7 +991,7 @@ export class SimpleCodeGeneratorAgent extends Agent<Env, CodeGenState> {
     /**
      * Execute phase implementation state - implement current phase
      */
-    async executePhaseImplementation(phaseConcept?: PhaseConceptType, staticAnalysis?: StaticAnalysisResponse, userContext?: UserContext): Promise<{currentDevState: CurrentDevState, staticAnalysis?: StaticAnalysisResponse}> {
+    async executePhaseImplementation(phaseConcept?: PhaseConceptType, userContext?: UserContext): Promise<{currentDevState: CurrentDevState, staticAnalysis?: StaticAnalysisResponse}> {
         try {
             this.logger().info("Executing PHASE_IMPLEMENTING state");
     
@@ -1014,33 +1012,19 @@ export class SimpleCodeGeneratorAgent extends Agent<Env, CodeGenState> {
                 ...this.state,
                 currentPhase: undefined // reset current phase
             });
-    
-            let currentIssues : AllIssues;
-            if (this.state.sandboxInstanceId) {
-                if (staticAnalysis) {
-                    // If have cached static analysis, fetch everything else fresh
-                    currentIssues = {
-                        runtimeErrors: await this.fetchRuntimeErrors(true),
-                        staticAnalysis: staticAnalysis,
-                    };
-                } else {
-                    currentIssues = await this.fetchAllIssues(true)
-                }
-            } else {
-                currentIssues = {
-                    runtimeErrors: [],
-                    staticAnalysis: { success: true, lint: { issues: [] }, typecheck: { issues: [] } },
-                }
-            }
+            
+            // Prepare issues for implementation
+            const currentIssues = await this.fetchAllIssues(true);
+            
             // Implement the phase with user context (suggestions and images)
             await this.implementPhase(phaseConcept, currentIssues, userContext);
     
             this.logger().info(`Phase ${phaseConcept.name} completed, generating next phase`);
 
             const phasesCounter = this.decrementPhasesCounter();
 
-            if ((phaseConcept.lastPhase || phasesCounter <= 0) && this.state.pendingUserInputs.length === 0) return {currentDevState: CurrentDevState.FINALIZING, staticAnalysis: staticAnalysis};
-            return {currentDevState: CurrentDevState.PHASE_GENERATING, staticAnalysis: staticAnalysis};
+            if ((phaseConcept.lastPhase || phasesCounter <= 0) && this.state.pendingUserInputs.length === 0) return {currentDevState: CurrentDevState.FINALIZING};
+            return {currentDevState: CurrentDevState.PHASE_GENERATING};
         } catch (error) {
             this.logger().error("Error implementing phase", error);
             if (error instanceof RateLimitExceededError) {
@@ -1102,19 +1086,13 @@ export class SimpleCodeGeneratorAgent extends Agent<Env, CodeGenState> {
             mvpGenerated: true
         });
 
-        const phaseConcept: PhaseConceptType = {
-            name: "Finalization and Review",
-            description: "Full polishing and final review of the application",
-            files: [],
-            lastPhase: true
+        const { result: phaseConcept, userContext } = await this.executePhaseGeneration(true);
+        if (!phaseConcept) {
+            this.logger().warn("Phase concept not generated, skipping final review");
+            return CurrentDevState.REVIEWING;
         }
         
-        this.createNewIncompletePhase(phaseConcept);
-
-        const currentIssues = await this.fetchAllIssues(true);
-        
-        // Run final review and cleanup phase
-        await this.implementPhase(phaseConcept, currentIssues);
+        await this.executePhaseImplementation(phaseConcept, userContext);
 
         const numFilesGenerated = this.fileManager.getGeneratedFilePaths().length;
         this.logger().info(`Finalization complete. Generated ${numFilesGenerated}/${this.getTotalFiles()} files.`);
@@ -1179,11 +1157,14 @@ export class SimpleCodeGeneratorAgent extends Agent<Env, CodeGenState> {
     /**
      * Generate next phase with user context (suggestions and images)
      */
-    async generateNextPhase(currentIssues: AllIssues, userContext?: UserContext): Promise<PhaseConceptGenerationSchemaType | undefined> {
+    async generateNextPhase(currentIssues: AllIssues, userContext?: UserContext, isFinal?: boolean): Promise<PhaseConceptGenerationSchemaType | undefined> {
         const issues = IssueReport.from(currentIssues);
         
         // Build notification message
         let notificationMsg = "Generating next phase";
+        if (isFinal) {
+            notificationMsg = "Generating final phase";
+        }
         if (userContext?.suggestions && userContext.suggestions.length > 0) {
             notificationMsg = `Generating next phase incorporating ${userContext.suggestions.length} user suggestion(s)`;
         }
@@ -1203,6 +1184,7 @@ export class SimpleCodeGeneratorAgent extends Agent<Env, CodeGenState> {
                 issues,
                 userContext,
                 isUserSuggestedPhase: userContext?.suggestions && userContext.suggestions.length > 0 && this.state.mvpGenerated,
+                isFinal: isFinal ?? false,
             },
             this.getOperationOptions()
         )
@@ -1495,7 +1477,13 @@ export class SimpleCodeGeneratorAgent extends Agent<Env, CodeGenState> {
      */
     async runStaticAnalysisCode(files?: string[]): Promise<StaticAnalysisResponse> {
         try {
+            // Check if we have cached static analysis
+            if (this.staticAnalysisCache) {
+                return this.staticAnalysisCache;
+            }
+            
             const analysisResponse = await this.deploymentManager.runStaticAnalysis(files);
+            this.staticAnalysisCache = analysisResponse;
 
             const { lint, typecheck } = analysisResponse;
             this.broadcast(WebSocketMessageResponses.STATIC_ANALYSIS_RESULTS, {
@@ -1616,6 +1604,9 @@ export class SimpleCodeGeneratorAgent extends Agent<Env, CodeGenState> {
     }
 
     async fetchAllIssues(resetIssues: boolean = false): Promise<AllIssues> {
+        if (!this.state.sandboxInstanceId) {
+            return { runtimeErrors: [], staticAnalysis: { success: false, lint: { issues: [], }, typecheck: { issues: [], } } };
+        }
         const [runtimeErrors, staticAnalysis] = await Promise.all([
             this.fetchRuntimeErrors(resetIssues),
             this.runStaticAnalysisCode()
@@ -1850,6 +1841,9 @@ export class SimpleCodeGeneratorAgent extends Agent<Env, CodeGenState> {
     }
 
     async deployToSandbox(files: FileOutputType[] = [], redeploy: boolean = false, commitMessage?: string, clearLogs: boolean = false): Promise<PreviewType | null> {
+        // Invalidate static analysis cache
+        this.staticAnalysisCache = null;
+        
         // Call deployment manager with callbacks for broadcasting at the right times
         const result = await this.deploymentManager.deployToSandbox(
             files,
diff --git a/worker/agents/operations/PhaseGeneration.ts b/worker/agents/operations/PhaseGeneration.ts
@@ -13,6 +13,7 @@ export interface PhaseGenerationInputs {
     issues: IssueReport;
     userContext?: UserContext;
     isUserSuggestedPhase?: boolean;
+    isFinal: boolean;
 }
 
 const SYSTEM_PROMPT = `<ROLE>
@@ -139,6 +140,69 @@ Adhere to the following guidelines:
 
 {{userSuggestions}}`;
 
+const LAST_PHASE_PROMPT = `Finalization and Review phase. 
+Goal: Thoroughly review the entire codebase generated in previous phases. Identify and fix any remaining critical issues (runtime errors, logic flaws, rendering bugs) before deployment.
+** YOU MUST HALT AFTER THIS PHASE **
+
+<REVIEW FOCUS & METHODOLOGY>
+    **Your primary goal is to find showstopper bugs and UI/UX problems. Prioritize:**
+    1.  **Runtime Errors & Crashes:** Any code that will obviously throw errors (Syntax errors, TDZ/Initialization errors, TypeErrors like reading property of undefined, incorrect API calls). **Analyze the provided \`errors\` carefully for root causes.**
+    2.  **Critical Logic Flaws:** Does the application logic *actually* implement the behavior described in the blueprint? (e.g., Simulate game moves mentally: Does moving left work? Does scoring update correctly? Are win/loss conditions accurate?).
+    3.  **UI Rendering Failures:** Will the UI render as expected? Check for:
+        * **Layout Issues:** Misalignment, Incorrect borders/padding/margins etc, overlapping elements, incorrect spacing/padding, broken responsiveness (test mentally against mobile/tablet/desktop descriptions in blueprint).
+        * **Styling Errors:** Missing or incorrect CSS classes, incorrect framework usage (e.g., wrong Tailwind class).
+        * **Missing Elements:** Are all UI elements described in the blueprint present?
+    4.  **State Management Bugs:** Does state update correctly? Do UI updates reliably reflect state changes? Are there potential race conditions or infinite update loops?
+    5.  **Data Flow & Integration Errors:** Is data passed correctly between components? Do component interactions work as expected? Are imports valid and do the imported files/functions exist?
+    6.  **Event Handling:** Do buttons, forms, and other interactions trigger the correct logic specified in the blueprint?
+    7. **Import/Dependency Issues:** Are all imports valid? Are there any missing or incorrectly referenced dependencies? Are they correct for the specific version installed?
+    8. **Library version issues:** Are you sure the code written is compatible with the installed version of the library? (e.g., Tailwind v3 vs. v4)
+    9. **Especially lookout for setState inside render or without dependencies**
+        - Mentally simulate the linting rule \`react-hooks/exhaustive-deps\`.
+
+    **Method:**
+    •   Review file-by-file, considering its dependencies and dependents.
+    •   Mentally simulate user flows described in the blueprint.
+    •   Cross-reference implementation against the \`description\`, \`userFlow\`, \`components\`, \`dataFlow\`, and \`implementationDetails\` sections *constantly*.
+    •   Pay *extreme* attention to declaration order within scopes.
+    •   Check for any imports that are not defined, installed or are not in the template.
+    •   Come up with a the most important and urgent issues to fix first. We will run code reviews in multiple iterations, so focus on the most important issues first.
+
+    IF there are any runtime errors or linting errors provided, focus on fixing them first and foremost. No need to provide any minor fixes or improvements to the code. Just focus on fixing the errors.
+
+</REVIEW FOCUS & METHODOLOGY>
+
+<ISSUES TO REPORT (Answer these based on your review):>
+    1.  **Functionality Mismatch:** Does the codebase *fail* to deliver any core functionality described in the blueprint? (Yes/No + Specific examples)
+    2.  **Logic Errors:** Are there flaws in the application logic (state transitions, calculations, game rules, etc.) compared to the blueprint? (Yes/No + Specific examples)
+    3.  **Interaction Failures:** Do user interactions (clicks, inputs) behave incorrectly based on blueprint requirements? (Yes/No + Specific examples)
+    4.  **Data Flow Problems:** Is data not flowing correctly between components or managed incorrectly? (Yes/No + Specific examples)
+    5.  **State Management Issues:** Does state management lead to incorrect application behavior or UI? (Yes/No + Specific examples)
+    6.  **UI Rendering Bugs:** Are there specific rendering issues (layout, alignment, spacing, overlap, responsiveness)? (Yes/No + Specific examples of files/components and issues)
+    7.  **Performance Bottlenecks:** Are there obvious performance issues (e.g., inefficient loops, excessive re-renders)? (Yes/No + Specific examples)
+    8.  **UI/UX Quality:** Is the UI significantly different from the blueprint's description or generally poor/unusable (ignoring minor aesthetics)? (Yes/No + Specific examples)
+    9.  **Runtime Error Potential:** Identify specific code sections highly likely to cause runtime errors (TDZ, undefined properties, bad imports, syntax errors etc.). (Yes/No + Specific examples)
+    10. **Dependency/Import Issues:** Are there any invalid imports or usage of non-existent/uninstalled dependencies? (Yes/No + Specific examples)
+
+    If issues pertain to just dependencies not being installed, please only suggest the necessary \`bun add\` commands to install them. Do not suggest file level fixes.
+</ISSUES TO REPORT (Answer these based on your review):>
+
+**Regeneration Rules:**
+    - Only regenerate files with **critical issues** causing runtime errors, significant logic flaws, or major rendering failures.
+    - **Exception:** Small UI/CSS files *can* be regenerated for styling/alignment fixes if needed.
+    - Do **not** regenerate for minor formatting or non-critical stylistic preferences.
+    - Do **not** make major refactors or architectural changes.
+
+<INSTRUCTIONS>
+    Do not make major changes to the code. Just focus on fixing the critical runtime errors, issues and bugs in isolated and contained ways.
+</INSTRUCTIONS>
+
+{{issues}}
+
+{{userSuggestions}}
+
+This phase prepares the code for final deployment.`;
+
 const formatUserSuggestions = (suggestions?: string[] | null): string => {
     if (!suggestions || suggestions.length === 0) {
         return '';
@@ -173,8 +237,9 @@ ${serialized}`;
     return serialized;
 };
 
-const userPromptFormatter = (issues: IssueReport, userSuggestions?: string[], isUserSuggestedPhase?: boolean) => {
-    let prompt = NEXT_PHASE_USER_PROMPT
+const userPromptFormatter = (isFinal: Boolean, issues: IssueReport, userSuggestions?: string[], isUserSuggestedPhase?: boolean) => {
+    let prompt = isFinal ? LAST_PHASE_PROMPT : NEXT_PHASE_USER_PROMPT;
+    prompt = prompt
         .replaceAll('{{issues}}', issuesPromptFormatterWithGuidelines(issues))
         .replaceAll('{{userSuggestions}}', formatUserSuggestions(userSuggestions));
     
@@ -191,7 +256,7 @@ export class PhaseGenerationOperation extends AgentOperation<PhaseGenerationInpu
         inputs: PhaseGenerationInputs,
         options: OperationOptions
     ): Promise<PhaseConceptGenerationSchemaType> {
-        const { issues, userContext, isUserSuggestedPhase } = inputs;
+        const { issues, userContext, isUserSuggestedPhase, isFinal } = inputs;
         const { env, logger, context } = options;
         try {
             const suggestionsInfo = userContext?.suggestions && userContext.suggestions.length > 0
@@ -201,10 +266,10 @@ export class PhaseGenerationOperation extends AgentOperation<PhaseGenerationInpu
                 ? ` and ${userContext.images.length} image(s)`
                 : "";
             
-            logger.info(`Generating next phase ${suggestionsInfo}${imagesInfo}`);
+            logger.info(`Generating next phase ${suggestionsInfo}${imagesInfo} (isFinal: ${isFinal})`);
     
             // Create user message with optional images
-            const userPrompt = userPromptFormatter(issues, userContext?.suggestions, isUserSuggestedPhase);
+            const userPrompt = userPromptFormatter(isFinal, issues, userContext?.suggestions, isUserSuggestedPhase);
             const userMessage = userContext?.images && userContext.images.length > 0
                 ? createMultiModalUserMessage(
                     userPrompt,
diff --git a/worker/agents/operations/PhaseImplementation.ts b/worker/agents/operations/PhaseImplementation.ts
